Phase 1 · SAO design decision — per-feature AGENT.md override scope (MVP vs. deferred)

[Luis85]

Meta

type: DesignDecision
stage: draft
maturity: L1
created: 2026-05-10
inputs:
  - "Luis85/specorator specs/specorator-agent-orchestrator/design.md — open question #1"
  - "#44 — prompt template system"
related: ["#43", "#44"]

Purpose. Decide whether per-feature AGENT.md overrides are in scope for V1 or deferred.

---

Context

The SAO design doc identifies this as open question #1. The WorkflowLoader reads stage-specific prompt templates from templates/agent-stages/ (→ #44), but leaves open whether individual features can override global templates via a per-feature file.

This matters because:

• Some features may require specialised prompts (e.g. a migration feature needs different requirements-stage guidance than a new-feature feature)
• Premature personalisation risks harness fragmentation before best-practice templates are established
• Per-feature overrides introduce a versioning and consistency maintenance burden

---

Options

Option A — MVP scope

Each feature can provide .specorator/{slug}/AGENT.md that overrides the global template for that stage. WorkflowLoader checks for the per-feature file before loading the global template.

• Pro: maximum flexibility; power users get full control
• Con: fragments the harness before global templates are proven; inconsistent agent behaviour across features

Option B — Deferred (recommended baseline)

V1 uses global templates only. Per-feature overrides are Phase 3+.

• Pro: forces investment in high-quality global templates first; consistent agent behaviour
• Con: no escape hatch for genuinely divergent feature types

Option C — Extension only

Per-feature files can extend but not replace global templates. The global harness constraints (success criteria, required sections) always apply; per-feature additions are appended.

• Pro: maintains harness integrity; allows customisation
• Con: template merging adds WorkflowLoader complexity

---

Recommendation

Start with Option B (deferred). Harness engineering best practice: establish strong global templates before allowing per-feature variation. The global templates in #44 should cover the 80% case; per-feature overrides can be phased in once the global templates are proven.

---

Acceptance

• Decision recorded (A / B / C) with rationale
• If A or C: WorkflowLoader spec updated to reflect override lookup logic
• If B: deferred item added to Phase 3+ backlog
• ADR or design note written
• Phase 1 · SAO prompt template system — feedforward harness guides and stage-template schema #44 (template system) updated with decision outcome