jdescopingtool/openspec/AGENTS.md

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:

# <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

- [ ] 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//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.