Problems with Claude following Agent OS instructions

[davidvictor]

I've been having trouble getting Claude to consistently follow the Agent OS instructions. Moving all references into my project folder helped a little bit but it's still basically 50/50 whether Claude follows the instructions. This potentially is an issue with the new version of Opus 4.1, but I am unsure. In order to fix this, I added this command to my claude.md:

`## 🚨 CRITICAL: Agent OS Command Execution

WHEN AN AGENT OS COMMAND IS INVOKED (from .claude/commands/), YOU MUST:

1. IMMEDIATELY read the referenced instruction file in .agent-os/instructions/
2. FOLLOW THE INSTRUCTIONS EXACTLY as written, step by step
3. EXECUTE ALL STEPS in the order specified, including:
   • Pre-flight checks
   • Process flows with numbered steps
   • Subagent invocations (use Task tool with appropriate agent type)
   • Conditional logic and error handling
4. DO NOT SKIP OR SIMPLIFY - Agent OS instructions are precise workflows that must be followed completely
5. INTERPRET XML-LIKE TAGS as structured instructions to follow, not as text to display

This is MANDATORY. Agent OS commands are core to this project's workflow.`

[swilco]

And has that fixed the issue?

[CasJam]

Thanks for raising this @davidvictor -- I've been noticing the same, especially the last few days (maybe Opus 4.1 behaves differently, not sure yet).

Specifically, I noticed when running /create-spec it often doesn't wait for my approval before proceeding to create the tasks list.

In my recent update, I did remove the previous CLAUDE.md instructions (to avoid context overload) but I'm considering adding back some direct instructions there, similar to what you suggested.

[SpongeBobCodePants]

Spoiler Alert: My final post shows the solution that worked for me.

I've tried Agent OS a few times, and I've never been able to get Claude to follow the execution plan correctly.

I set up Agent OS in a new project tonight. Classic ToDo app for testing. No core installation (just project level) and didn't do any manual editing of .md files. When I ran /execute-tasks, the workflow specified in execute-tasks.md was completely bypassed. Claude just went right to work on the tasks. So, I decided to interrogate Claude.

I wondered if the presence of numbered steps in tasks.md and execute-tasks.md would cause confusion. Claude agreed this was a problem but later explained that it completely ignored execute-tasks.md, lol. Maybe it isn't the numbers but the use of the word "tasks" that is confusing. A potentially useful suggestion was to put a reminder in tasks.md. Yet, this feels like a band-aid. When we run a command, Claude shouldn't ignore the instructions in that file. However, Claude stated it may have been confused about which .md files were explicit instructions. I have no idea if using Claude to self-diagnose is useful.

I'll test more when I can. Here are a few of the responses in case they are useful.

Claude on the step confusion (which was contradicted by saying execute-tasks.md was completely ignored):

What Went Wrong - My Confusion:

Mixed Up Two Different Step Types:

1. Agent OS Workflow Steps (execute-tasks.md) - The 6-step process for HOW to
   .execute tasks
2. Implementation Tasks (tasks.md) - The WHAT to implement (the actual todo items)

I treated the tasks.md items (1.1, 1.2, etc.) as if they were the complete
workflow, when they're actually just the implementation checklist that should be
.executed WITHIN Step 5 of the proper workflow.

Skipped Critical Workflow Steps:

• No task assignment confirmation
  -No context gathering from required docs
• No git branch management
• No development server checks
• Didn't use execute-task.md for implementation

Suggestions to Make This Clearer:

1. Naming Clarification:

The confusion comes from both files having "steps" but serving different purposes:

• Maybe rename tasks.md items as "Implementation Items" or "Deliverables" instead
  of "Tasks"
• Or add clear headers like "Workflow Steps" vs "Implementation Checklist"

2. Cross-Reference Instructions:

In execute-tasks.md Step 5, add explicit reminder:
"Execute tasks from tasks.md following execute-task.md workflow -
DO NOT implement tasks.md items directly"

3. Workflow Reminder in tasks.md:

Add header to tasks.md:

Implementation Checklist

These items should be executed using the workflow in execute-tasks.md
Do NOT implement these directly - follow the 6-step execution process

4. Agent Training:

I should have recognized that instructions ending in ".md" are workflows to follow,
not just reference documents.

What Would Help Me Most:

1. Clear distinction between "workflow steps" (how to work) vs "implementation
   tasks" (what to build)
2. Explicit reminders in files about which other files to reference
3. Better understanding that .md files in instructions/ are processes, not just
   documentation

The real issue was I saw tasks.md and immediately started coding instead of
recognizing I needed to follow the execute-tasks.md workflow first.

Another interesting response:

You're absolutely right - I completely ignored execute-tasks.md entirely.

Looking back at what I did:

• I never even read execute-tasks.md
• I never executed the pre-flight check
• I never followed any of the 6 workflow steps
• I went straight from reading the spec to implementing code

I completely bypassed the entire Agent OS execution framework and just started
coding based on the tasks.md file alone.

What I should have done first:

1. Read execute-tasks.md
2. Execute the pre-flight check (@.agent-os/instructions/meta/pre-flight.md)
3. Follow Step 1: Task Assignment
4. And so on through the proper workflow

What I actually did:

• Saw tasks.md
• Started implementing Task 1 directly
• Completely ignored that there was an execution workflow to follow

This is a fundamental failure to follow the Agent OS process. I treated it like a
regular coding request instead of recognizing I was in an Agent OS environment with
specific workflows to follow.

The real issue: I didn't even look for execute-tasks.md or recognize that
/execute-tasks meant "follow the execute-tasks.md workflow." I just saw tasks and
started executing them directly.

This suggests I need much more explicit instruction to always check for and follow
workflow files before doing any implementation work in Agent OS environments.

[SpongeBobCodePants]

I also cleared context and asked Claude to analyze the workflow and then asked specifically about /execute-tasks.

I can see the problem. The execute-tasks command is particularly thin - just 3 lines
with a vague reference. Here are the likely reasons Claude ignores the referenced
instructions:

Root Causes:

1. Weak directive language: "Refer to the instructions" is not a strong command.
   Claude may interpret this as optional reference material rather than mandatory
   execution steps.
2. No explicit instruction to read the file: Unlike other commands that might say
   "Read and follow..." or "Execute the steps in...", this just says "refer to."
3. Generic task description: "Execute the next task" is vague - Claude might try to
   infer what to do rather than following the referenced workflow.
4. File path complexity: The complex 6-step workflow in execute-tasks.md (189 lines)
   might be overwhelming when only referenced, not directly included.

Potential Solutions:

1. Strengthen the command language:

Execute Tasks

IMPORTANT: Read and execute ALL steps from:
@.agent-os/instructions/core/execute-tasks.md

Follow the complete 6-step process exactly as specified.
2. Add explicit file reading instruction:
First, read the complete instructions from
@.agent-os/instructions/core/execute-tasks.md
Then execute each step in the process_flow sequentially.
3. Include a summary of key steps in the command file itself as a backup.

The issue is likely that the reference is too weak and Claude defaults to its own
interpretation rather than following the complex referenced workflow.

[SpongeBobCodePants]

Well, I guess I'm all in on this tonight. I suspect some of Claude's feedback were false flags. I cleared context again and modified create-tasks.md to look like this:

Create Tasks

Follows the specified workflow for creating a tasks list with sub-tasks to execute a feature based on its spec.

Rigorously execute the workflow located in this file:
@.agent-os/instructions/core/create-tasks.md

It worked beautifully. Absolutely perfect. This was a very small test with a "fake" To Do app, but the results were promising. Maybe Claude does know what it needs, lol.