Joseph Doherty
26ff8d9b4f
Set up repository with legacy .NET Framework 4.8 source (OLD/), new .NET 10 Blazor solution (NEW/), OpenSpec specifications, documentation, and project configuration.
120 lines
3.3 KiB
Markdown
120 lines
3.3 KiB
Markdown
# 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.
|