Skip to content

feat(agent-ready): add session-startup, DoD, and JSON-ledger guidance#38

Open
dgalarza wants to merge 1 commit into
mainfrom
feat/agent-ready-harness-patterns
Open

feat(agent-ready): add session-startup, DoD, and JSON-ledger guidance#38
dgalarza wants to merge 1 commit into
mainfrom
feat/agent-ready-harness-patterns

Conversation

@dgalarza
Copy link
Copy Markdown
Owner

Summary

Adds three patterns to the AGENTS.md template drawn from Anthropic's harness design articles (Effective harnesses for long-running agents, Harness design for long-running application development), addressing failure modes the existing scaffold did not cover:

  • Session Startup — bearing-getting ritual (pwd, git log, smoke test) agents run on every fresh context. Prevents the "look around, declare done" failure mode where an agent piles new work on top of an existing broken state.
  • Definition of Done — codifies end-to-end verification before marking work complete. Targets the most common over-confidence failure: agents shipping changes because "unit tests pass" without exercising the feature end-to-end.
  • JSON over Markdown for ledgers — short note in Template Notes capturing Anthropic's finding that agents are far less likely to inappropriately edit JSON files than Markdown ones. Useful guidance when a project adds a task ledger or feature-status file.

agents-md mode populates Session Startup and DoD during generation using detected build/test commands. audit mode now checks for both sections, flags DoD sections that omit end-to-end verification, and offers matching auto-fixes.

Bumps agent-ready to 1.3.0 in plugin.json and marketplace.json.

Test plan

  • Run audit mode against a project missing Session Startup — confirm it flags as missing and offers fix
  • Run audit mode against a project with DoD but no end-to-end mention — confirm "present but does not mention end-to-end verification" warning fires
  • Run agents-md mode on a fresh project — confirm generated AGENTS.md contains both new sections with detected commands filled in
  • CI: skill validator + JSON validation pass

Three additions to the AGENTS.md template drawn from Anthropic's harness
design articles, addressing failure modes that the existing scaffold did
not cover:

- Session Startup: a bearing-getting ritual (pwd, git log, smoke test)
  agents run on a fresh context. Prevents the "look around, declare done"
  failure mode where an agent piles new work on top of an existing
  broken state.
- Definition of Done: codifies end-to-end verification before marking
  work complete. Addresses the most common over-confidence failure --
  agents shipping changes based on "unit tests pass" without exercising
  the feature end-to-end.
- JSON over Markdown for ledgers: short note in Template Notes capturing
  Anthropic's finding that agents are far less likely to inappropriately
  edit JSON files than Markdown ones.

Audit mode now checks for the presence of Session Startup and Definition
of Done sections, flags DoD sections that omit end-to-end verification,
and offers auto-fixes for both. agents-md mode populates both sections
during generation using detected commands.

Bumps agent-ready to 1.3.0 in plugin.json and marketplace.json.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant