# OpenSpec Agent Guidelines

## Conventions

### Change IDs
- Use verb-led identifiers (e.g., `add-user-auth`, `migrate-signalr`, `refactor-search`)
- Keep IDs short but descriptive

### Proposal Structure
```
changes/<change-id>/
  proposal.md    # Summary, scope, acceptance criteria
  tasks.md       # Ordered work items with checkboxes
  design.md      # (optional) Architecture decisions
  specs/         # Spec deltas organized by capability
```

### Spec Structure
```
specs/
├── domain-models/      # Entity definitions
├── database-schema/    # SQL Server tables for DbUp
├── data-access/        # JDE/CMS/SQL repositories
├── data-sync/          # Cache refresh scheduling
├── search-processing/  # Criteria and query building
├── excel-export/       # Result formatting
└── web-api-auth/       # API endpoints and authentication
```

### Spec Template

Each spec follows this structure:

```markdown
# <Functional Area> Specification

## Overview
Brief description of this area's purpose and scope.

## Source Reference
| Legacy Files | Purpose |
|--------------|---------|
| OLD/path/to/file.cs | What this file does |

## Requirements

### Requirement: <Name>
<Behavior description - what it does, not how>

#### Inputs
- Parameter/data inputs

#### Outputs
- What is returned/produced

#### Business Rules
- Validation rules
- Edge cases
- Error conditions

#### Scenarios
**Scenario: <Happy path>**
Given <context>
When <action>
Then <expected result>

**Scenario: <Edge case>**
Given <context>
When <action>
Then <expected result>

## Migration Notes
| Legacy Pattern | New Pattern | Rationale |
|----------------|-------------|-----------|
| Example legacy pattern | Example new pattern | Why the change |

## Open Questions
- Any ambiguities found during analysis
```

### Task Format
```markdown
- [ ] Task description
  - Validation: How to verify completion
  - Dependencies: What must be done first (if any)
```

## Session Workflow

When writing specs, follow this workflow:

1. **SCOPE** - Identify legacy files to analyze
2. **ANALYZE** - Read files, extract behaviors and business rules
3. **DRAFT** - Write spec.md following the template
4. **REVIEW** - Use Codex MCP to validate accuracy and completeness
5. **COMMIT** - Save to SPECS/specs/<area>/spec.md

### Codex MCP Review

After drafting each spec, use `mcp__codex__codex` to:
- Cross-reference spec requirements against legacy source files
- Identify any missed behaviors or edge cases
- Verify business rules are accurately captured
- Flag any ambiguities or gaps

## Principles

1. **Behavior-focused** - Document WHAT, reference OLD files for HOW
2. **Scenario-driven** - Concrete examples using Given/When/Then
3. **Migration-aware** - Inline notes for architecture changes
4. **Traceable** - Every requirement links back to source files
5. **Minimal scope** - Only what's needed for the change
6. **Verifiable tasks** - Each task has clear completion criteria
7. **Incremental progress** - Break large changes into smaller, shippable pieces
8. **Design before code** - proposal.md and design.md before implementation

## Execution Plan

See `PLANS/legacy-spec-capture-plan.md` for the full execution plan with 7 session checklists.