Claude does not always follow the instructions in agent-os:shape-spec (Proposed fix)

[stephanlotter]

I often get that Claude Code does not follow the instructions in the shape-spec.md file. It would just follow its own process.

I added **IMPORTANT** Always follow the step in this guide for the planning phase to the very bottom of the shape-spec.md file and it has been following the instruction since.

[sandroden]

Are you talking about agent-os v2 or v3?

[stephanlotter]

v3

[diegoserranobst]

v3 also here

[diegoserranobst]

Problem

When running /shape-spec inside Claude Code's plan mode, the agent skips Step 7 / Task 1: Save Spec Documentation and saves the plan only to Claude Code's internal plan file (.claude/plans/<random-name>.md) instead of the expected agent-os/specs/{YYYY-MM-DD-HHMM-feature-slug}/ folder.

Expected Behavior

The shape-spec skill clearly defines in Step 7:

Task 1 always being "Save spec documentation"

The spec folder should be created as:

agent-os/specs/{YYYY-MM-DD-HHMM-feature-slug}/
├── plan.md
├── shape.md
├── standards.md
├── references.md
└── visuals/        (if any)

This should happen before any implementation tasks.

Actual Behavior

1. The agent writes the plan only to .claude/plans/purring-dancing-pudding.md (Claude Code's system file)
2. Steps 6 (Generate Spec Folder Name) and 7 (Structure the Plan with Task 1) are skipped entirely
3. The agent-os/specs/ folder is never created
4. The spec documentation (shape.md, standards.md, references.md) is never generated

The issue was only caught when the user noticed and asked why the spec wasn't saved to the correct location. The agent then had to retroactively create the spec folder after implementation was already complete.

Root Cause

There's a conflict between two planning systems:

1. Claude Code plan mode — Requires writing to a specific .claude/plans/<name>.md file and calling ExitPlanMode for approval
2. shape-spec skill — Expects the plan to include Task 1 that creates agent-os/specs/ with multiple files

The agent prioritizes the Claude Code plan mode constraints (write to .claude/plans/, call ExitPlanMode) and loses track of the shape-spec's own spec-saving requirements. The shape-spec skill's Step 7 instruction to "always make Task 1 = Save Spec Documentation" gets absorbed into the plan file content but is never structured as an actual executable task.

Suggested Fix

Options to consider:

1. Make shape-spec aware of plan mode: If in plan mode, the skill should explicitly instruct the agent to include the spec folder creation as Task 1 in the .claude/plans/ file, with a clear note that this task creates agent-os/specs/ — not that the plan file is the spec.

2. Create spec folder during shaping: Instead of deferring spec creation to Task 1 of implementation, create the spec folder (shape.md, standards.md, references.md) during the shaping phase itself (these are read-only artifacts documenting decisions, not code changes). Only plan.md would be deferred to after implementation begins.

3. Add a post-implementation reminder: The skill could include a final step that checks whether agent-os/specs/ was created and reminds the agent to do so if not.

Reproduction

1. Enter plan mode
2. Run /shape-spec
3. Complete the shaping conversation
4. Approve the plan and implement
5. Observe that agent-os/specs/ was never created