playbooks

home / skills / mduongvandinh / skills-java-spring / spring-openspec

spring-openspec skill

/java-spring-skills/skills/workflow/spring-openspec

This skill enables spec-driven Spring Boot development by aligning on OpenSpec requirements before coding, improving consistency and delivery.

This is most likely a fork of the java-spring-skills skill from mduongvandinh
npx playbooks add skill mduongvandinh/skills-java-spring --skill spring-openspec

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.8 KB
---
name: spring-openspec
version: 1.0.0
description: |
  Spec-First Development with OpenSpec for Spring Boot.
  Align on specifications before implementation begins.

triggers:
  - "new feature"
  - "spec first"
  - "openspec"
  - "specification"
  - "proposal"
---

# OpenSpec - Spec-Driven Development

## Workflow

```
┌──────────────────────────────────────────────────────────────┐
│                    OPENSPEC WORKFLOW                          │
│                                                               │
│  ┌──────────┐    ┌──────────┐    ┌───────────┐    ┌────────┐│
│  │ PROPOSAL │───→│  REVIEW  │───→│ IMPLEMENT │───→│ARCHIVE ││
│  │          │    │          │    │           │    │        ││
│  │ Draft    │    │ Align    │    │ Code      │    │ Merge  ││
│  │ Specs    │    │ Together │    │ Tasks     │    │ Specs  ││
│  └──────────┘    └──────────┘    └───────────┘    └────────┘│
└──────────────────────────────────────────────────────────────┘
```

## Directory Structure

```
openspec/
├── AGENTS.md           # Instructions for AI assistants
├── specs/              # Authoritative specifications
│   ├── auth/
│   ├── user/
│   └── order/
└── changes/            # Proposed modifications
    └── feature-xxx/
        ├── proposal.md
        ├── tasks.md
        └── spec-delta.md
```

## Commands

| Command | Description |
|---------|-------------|
| `/openspec-proposal <name>` | Create new proposal |
| `/openspec-review` | Review and align |
| `/openspec-implement <name>` | Implement from spec |
| `/openspec-archive <name>` | Archive completed feature |

## Proposal Template

```markdown
# Proposal: Feature Name

## Objective
What we want to achieve.

## Scope
- Item 1
- Item 2

## Out of Scope
- Not included

## Success Criteria
- Criterion 1
- Criterion 2

## Dependencies
- Dependency 1
```

## Spec Template

```markdown
# Feature Specification

## API Endpoint
POST /api/v1/resource
...

## Business Rules
1. Rule 1
2. Rule 2

## Data Model
@Entity...

## Sequence Diagram
Client -> Controller -> Service -> Repository
```

## Reference in Code

```java
/**
 * Service description.
 *
 * @spec openspec/specs/feature/spec-name.md
 */
@Service
public class MyService {
    // Implementation
}
```

Overview

This skill enables spec-first development for Spring Boot projects using OpenSpec. It helps teams create, review, implement, and archive authoritative API and feature specifications before writing code. The workflow integrates proposals, reviews, implementation tasks, and archival steps to keep specs and code aligned.

How this skill works

The skill organizes specifications in a dedicated specs directory and tracks proposed changes in a changes area. Commands create proposals, trigger reviews, scaffold implementation tasks, and archive completed features. It also provides templates for proposals and full feature specifications so developers and AI agents reference the authoritative source while implementing code in Java Spring.

When to use it

  • Starting a new API or feature where team alignment is required before coding
  • Coordinating cross-functional design reviews between product, design, and engineering
  • Onboarding new contributors so they can implement against an authoritative spec
  • Managing iterative changes and proposals without diverging code and docs
  • Automating task creation from agreed specifications for implementation

Best practices

  • Draft a concise proposal that states objective, scope, out-of-scope items, and success criteria
  • Use the spec template to document endpoints, business rules, data models, and sequence diagrams
  • Keep specs authoritative: reference spec files in service Javadoc or annotations
  • Create small, focused change proposals to simplify reviews and implementation
  • Run a formal review step to align stakeholders before generating implementation tasks

Example use cases

  • Propose and review a new authentication flow with clear API and data model before coding
  • Create a feature proposal for an order processing change, then generate implementation tasks
  • Annotate services with spec references so automatic tools and developers know the source of truth
  • Archive completed feature specs after merge to maintain a clean spec history
  • Use the review command to gather feedback and reach agreement on business rules

FAQ

How do I start a new feature proposal?

Use the proposal command to create a new proposal file and fill the template with objective, scope, and success criteria.

Where should I put authoritative API definitions?

Store them in the specs directory and reference the spec path in service code comments so implementation traces back to the spec.