Agent instructions don't organize specs by domain (flat <capability>/ layout instead of <domain>/<capability/>)

[c4patino]

Summary

Every agent-facing instruction in the codebase tells the agent to write specs at specs/<capability>/spec.md — a flat, one-level-deep layout. Human-facing documentation (docs/concepts.md, docs/existing-projects.md) describes organizing specs by domain (e.g., specs/auth/, specs/payments/), but that nested pattern is never surfaced in agent instructions.

The internal code already supports nested layouts (spec-discovery.ts, validator.ts, specs-apply.ts, change-parser.ts all handle specs/<area>/<capability>/spec.md), so the gap is purely in agent-facing guidance.

Affected files

1. schemas/spec-driven/schema.yaml:62-64 — The authoritative schema instruction tells agents specs/<capability>/spec.md (flat, no domain).
2. All skill templates (src/core/templates/workflows/propose.ts, explore.ts, sync-specs.ts, archive-change.ts) — Reference specs/<capability>/spec.md.
3. All SKILL.md files (skills/openspec-propose/SKILL.md, openspec-explore/, openspec-sync-specs/, openspec-archive-change/) — Same flat pattern.
4. openspec/specs/openspec-conventions/spec.md — Structure diagram shows [capability]/ without a [domain]/ level.
5. src/core/validation/validator.ts:165 and src/core/parsers/spec-structure.ts:47 — User-facing error messages use the flat path pattern.

Expected behavior

Agents should be instructed to organize specs by domain under specs/<domain>/<capability>/spec.md. The schema instruction and all skill templates should reflect this.

Root cause

The schema instruction has been specs/<capability>/spec.md since spec-driven was introduced, and every skill template and skill file copied that pattern. The human docs show domain organization but the agent instructions never caught up.

Suggested approach

1. Update schemas/spec-driven/schema.yaml instruction to tell agents to group specs by domain, look at existing domain directories, and create new ones as needed.
2. Update the path patterns in all skill templates and SKILL.md files to use specs/<domain>/<capability>/spec.md.
3. Update the conventions spec structure diagram to include the domain level.
4. Update user-facing error messages in the validator and parser.
5. Add guidance about how agents should determine the appropriate domain for a capability (existing domains take precedence; create a new short kebab-case domain if none fits).

Note: I have a local branch with all these changes applied that I can share if it would help kickstart the PR.

[xg-gh-25]

This is a clean articulation of the flat-vs-nested gap — and the root cause (schema instruction has been flat since introduction, every template copied it) matches what we hit on our own spec-driven pipeline when agent instructions and implementation diverged.

Two observations from production:

1. Domain-first organization is a forcing function for bounded contexts

When specs live at specs/<capability>/, naming collisions push agents toward generic names (auth-service, payments-service) that blur boundaries. When specs live at specs/<domain>/<capability>/, the domain prefix acts as a natural namespace — identity/auth/, billing/payments/ — and agents gravitate toward capability names that are specific within their domain but don't need to be globally unique.

We saw this in a polyglot codebase with ~40 specs across 6 domains: the flat layout produced 8 name collisions (resolved with suffixes: auth-api, auth-worker) before we restructured domain-first. After restructure, zero collisions, and the spec names became shorter and more precise because the domain directory carried half the context.

2. The code already supporting nested layouts is the green light

spec-discovery.ts, validator.ts, specs-apply.ts, and change-parser.ts all handle specs/<area>/<capability>/spec.md — that's the tell that this isn't a breaking change to the runtime, it's purely instruction hygiene. The validator and parser already recurse directories, so switching the schema instruction from "write at specs/<capability>/" to "group by domain under specs/<domain>/<capability>/" is a documentation change, not a refactor.

If you have the local branch ready, that's probably the fastest path to close this — the instruction delta is mechanical (schema + templates + SKILL.md files + error messages), and the test surface is small (existing nested-layout tests already cover the discovery/validation logic).

For determining domain boundaries when creating new specs: we use a "look at siblings first" heuristic — if there's an existing specs/identity/ or specs/billing/, use that; if not, create a new short kebab-case domain. That rule keeps domain proliferation low (agents default to reusing existing domains) while staying flexible.

---

This came out of our spec-driven autonomous pipeline work in SwarmAI. Discussion: T-DDD (Domain-Driven Development)