Agent OS 2.0 🚀

[CasJam]

Agent OS 2.0 is a major new release that brings several core architectural changes and improvements.

The big headline here is the dual mode architecture for supporting both multi-agent tools (Claude Code) and single-agent tools (every other tool).

this page documents:

• The new features in Agent OS 2.0
• Architectural changes in 2.0
• What changed from 1.x
• Updating guide

The Agent OS docs also received a complete overhaul and expansion. It's now broken out into multiple pages that document every detail of how to install, use and customize Agent OS.

---

This discussion was created from the release Agent OS 2.0 🚀.

[ssr1ram]

I just installed and went from plan-product to implement-spec - I used vscode + vibe-kanban with gemini and qwen-code

Initial thoughts: ultra-cool - great job

the process was extremely smooth.

• your YYYY-MM-DD- allows for multiple feature specs which for me was crucial
• your new directory structure is cetainly more intuitive and extensible

things that could be sharpened are

• task scheduling
  • holding some tasks from the tasks shared to be done at a later time - some form of task scheduling
• task registry
  • not having each task go back and mark itself done in tasks.md - maybe marking Done some other way

Some minor issues

1. neither gemini nor qwen liked "run this' they preferred "execute .md"
2. typo : In https://buildermethods.com/agent-os/implement-spec under single agent mode you have
   @agent-os/commands/implement-spec/1-implement-spec.md run this
   the actual file is implement-spec.md not 1-implement-spec.md

Thanks for putting this out, it certainly knows how to talk to the LLM's

[CasJam]

Thanks!

your YYYY-MM-DD- allows for multiple feature specs which for me was crucial

Ya this has been there since 1.x. I like to see the spec folders in chronological order. However I noticed when I create multiple specs in the same day, this order doesn't work (considered adding a time to the folder name, but not sure yet).

holding some tasks from the tasks shared to be done at a later time - some form of task scheduling

Not sure about the scheduling piece, without some other tooling for this. But you should be able to instruct your agent to "only execute tasks 1 and 2" etc.

And in single-agent mode, each task group gets its own prompt, so you can manually decide which task groups to execute when you're ready.

not having each task go back and mark itself done in tasks.md - maybe marking Done some other way

Interesting - not sure I understand why you wouldn't want tasks to be marked as done if they were done? Perhaps you'd prefer to check them off manually after you review?

Version 1.x seemed to check them off only 50% of the time and v2.0 was designed to ensure they get checked more reliably (that's how I'd want it).

...

Clarified and fixed those docs! 👍

[ssr1ram]

Not sure about the scheduling piece, without some other tooling for this. But you should be able to instruct your agent to "only execute tasks 1 and 2" etc.

The issue here is that there needs to be one single source of truth.

• The first problem is in the generation of spec.md when in response to the questions create-spec.md asks it moves all the tasks noted to be done later as "out-of-scope"
• So now spec.md has them as out of scope and tasks.md does not even produce tasks for them
• This knowledge remains buried in planning and I need to remember to pluck out those tasks I had reserved for a later time. I am doing this by marking the "answers I send" (my hand-written prompts (hwp's)) in a structured manner

Interesting - not sure I understand why you wouldn't want tasks to be marked as done if they were done? Perhaps you'd prefer to check them off manually after you review?

• Now, I have the (immediate) tasks.md with a grouping of major tasks each with a number of sub-tasks
• I send prompt 1 to the LLM. It runs through them and claims to have done it.
• I review and realize that it did do something but not exactly what i wanted or the way i needed it
• I now start sending hwp'sto fix this. This brings up new issues
  • i need to remain in the chat context of the original prompt.
  • I hope the LLM will remember to follow all the directives given earlier, because my hwp does not restate them as I don't have an easy way to craft/assemble a well thought out and comprehensivehwp
• All this while the task is marked done when it is really in review (this is the kanban bit that backlog.md, taskmaster-ai and vibe-kanban manage)

I think that agent-os brings process with grammar and directives to the table.

• If agent-os were to expose them in a more granular manner, hwp's can be assembled that can now take advantage of the rich thinking in agent-os.
• task completion with bug fixes and user changes can be reliably done
• task co-ordination across dependent features can be accomplished. This could be extended to multiple repos.
• A library of new grammar / directives (in md snippets) can be provided by the community to have hwp's make LLM's aware of for e.g. the task management tooling they are using i..e task-master or backlog etc.

[hcprieto]

Thanks!! It looks great!

The documentation at https://buildermethods.com/agent-os/version-2 describes how to perform the migration in case Agent OS 1.x was used in a project.

It does not mention, however, what is the best way to handle the existing /product and /specs folders within the old /.agent-os

• Should they just be copied to /agent-os?
• Should any Agent OS command be executed to review/update the plans to the updated Agent OS?

Some brief guidance on these aspects would be a valuable addition.

[morydin]

I am also wondering about this. It isn't clear exactly how this should be handled. I assume it's OK to just move the entire product folder over to the new agent-os folder?

[hcprieto]

I actually asked claude to inspect the new Claude commands (that create a new spec and add detailed phases and tasks), and to use that knowledge to adapt the existing specs into the format they would have had with the command. It did a good work, assigning sub-agents to each of the tasks, incorporating some mockups to the specs (with some extra prompting from me), etc.

[CasJam]

You can simply move the /product and /specs folders from your project's 1.x .agent-os folder into your 2.0 agent-os.

I just updated the migration guide 👍 https://buildermethods.com/agent-os/version-2