Adding a new skill for spec conflict resolutions

[B2F]

Wouldn't it be nice to have a rule in Agent.md, by default, so that AI ask the user what to do (update archived spec / create new proposal / update current tasks) if it finds specifications discrepancies ?

Usecase A:
You work on an update that is small enough that you don't want to burn tokens going through the whole proposal - changes - archive process.

Usecase B:
You work on a new feature proposal that is conflicting with archived specs, and you forgot it was there.

Usecase C:
You work on features manually and bypass AI completely (or mixed usage), only later on you trigger Agent.md

I think the complete OpenSpec workflow is too heavy for rational use in everyday tasks, and that is creating a risk of creating a pile of outdated / not maintained specs.

OpenSpec power IMO is that is can be plugged into any project at any stage, the perfect Agent.md in my opinion would reflect this by creating specs iteratively while work is done at any stage, on demand.

In essence I would suggest adding a new conflict resolution skill which would provide with clear options for the user :

• add proposal
• update tasks
• update archives

That is, if a spec conflict is found.

[TabishB]

We've moved away from AGENTS.md and towards skills. We'll probably overhaul some of the skills so agents know how to navigate some of these changes better.

But it's a tricky balance. Sometimes you don't want the openspec to be triggered by the agent.

[B2F]

What if the new task or update is conflicting archived specs ? openspec list wouldn't pick it up.
Isn't openspec supposed to read archived specs as well ?

EDIT: thanks, I didn't realize my openspec was outdated. But could you iterate over how conflicts are managed and how is it affecting archived specs and those use cases not triggering openspec ?

[B2F]

I renamed this discussion to "Adding a new skill for spec conflict resolutions".

Before, with Agent.md we had:

### Change Conflicts
1. Run `openspec list` to see active changes
2. Check for overlapping specs
3. Coordinate with change owners
4. Consider combining proposals

In my opinion this was already lacking access to archived specs (openspec list --specs).

@TabishB what is your view on this #199 ?

To me it's still not clear how we should navigate Openspec with brownfield project or those 3 use-cases presented in this discussion ? (or if there is currently any work in progress on this topic).

[TabishB]

for #199

from a previous thread:

the temptation here is usually to reverse-engineer ALL specs from existing code. I would avoid this approach and instead aim for more incremental adoption. (Adding in reviewed specs as you go)

The only thing worse than no specs is incorrect specs 😕

Bulk-creating incorrect or unverified specs usually leads to worse outcomes

[B2F]

Ok but it still doesn't explain how archived specs should be considered, nor how specs conflicts should be resolved.

For instance, is it fine by you that archived specs become severely outdated and inaccurate ?

EDIT: so if I understand correctly openspec goal is not to document the project nor providing guidelines for new contributors, only to drive focus on current tasks in the open.

[B2F]

We'll probably overhaul some of the skills so agents know how to navigate some of these changes better.

@TabishB , which improvements do you have in mind ?

[TabishB]

Ok but it still doesn't explain how archived specs should be considered, nor how specs conflicts should be resolved.

Ok there's 2 scenarios.

1. You're using openspec to make a change

You don't have to worry about considering existing specs since we tell the model to take a look at them before creating the proposal (i.e the spec deltas).

Reconciliation happens when you archive here same as before.

2. You're NOT using openspec to make a change

Then, yes, you run a risk of updating functionality that causes a "spec drift" (drift between the specified behavior and the code).
Same as if you work on a project where you have a teammate who's not using OpenSpec and is updating code without updating any specs.
Same as people forgetting to update documentation.

Currently, there's no easy way to reconcile this.

Some models like (GPT Codex 5.4) are better at doing reconcilation without being told. (For example i've told codex multiple times to make a change that didn't use openspec and it updated the specs when it realised it would cause a drift there).

We DO want to introduce either a skill and/or tooling to make this easier for models to detect and check. In some cases I've seen some people setup CI that runs every 5 merge's or so to check if the code commited would cause any drift as well.

You do have to keep in mind that adding a skill/agents.md does not mean that specs never go out of date, there's always a chance because models are not perfect either. They have repeatedly forgotten what's in AGENTS.md and have also failed to call skills when needed.

So to answer the following question: "For instance, is it fine by you that archived specs become severely outdated and inaccurate ?
"

obviously not, but we need to do our best for it not to happen.

EDIT: so if I understand correctly openspec goal is not to document the project nor providing guidelines for new contributors, only to drive focus on current tasks in the open.

What? Please clarify

[B2F]

Some models like (GPT Codex 5.4) are better at doing reconcilation without being told. (For example i've told codex multiple times to make a change that didn't use openspec and it updated the specs when it realised it would cause a drift there).

Indeed I also had Codex (5.3) update drifted specs but it's not clear at which point this was part of the workflow or a random action.

EDIT: so if I understand correctly openspec goal is not to document the project nor providing guidelines for new contributors, only to drive focus on current tasks in the open.

What I mean by that:

• Guidelines for new contributors: since AGENTS.md is removed, we loose default guidelines about openspec usage in the project, and
• Documenting the project: as far as I know archived specs are not evaluated against current changes ? At least not until those changes are validated and archived, but even then I am unsure what really is intended.
• Drive focus on current tasks in the open: solely focusing on active changes

If the plan is to iteratively maintain accurate specs all along, shouldn't changes also be explicitly evaluated against archives for conflicts prevention,before writing them ? Because even when we start or explore a new feature, archived specs could contain relevant information.

Maybe I am still missing an important part of openspec vision / workflow.