diff --git a/.cursor/agents/robot-coordinator.md b/.cursor/agents/robot-coordinator.md index 7640cb67..8226e585 100644 --- a/.cursor/agents/robot-coordinator.md +++ b/.cursor/agents/robot-coordinator.md @@ -75,10 +75,31 @@ When the user points you at a `*.plan.md` (under `.cursor/plans/`, `requirements - Handoffs must include **group id**, **task ids**, paths, and dependency status (e.g. "Parallel=A1 verified; Parallel=A2 may start"). - Follow project conventions from AGENTS.md (Maven, Git workflow, boundaries). +### OpenSpec task list updates + +When you receive an OpenSpec task list (either from a `*.plan.md` or an OpenSpec folder structure with `changes/*/tasks.md`), you **MUST** update the task status after completion: + +1. **Identify OpenSpec tasks:** Look for `tasks.md` files with OpenSpec checkbox format (`- [ ]` / `- [x]`) +2. **Track completion:** As delegated agents complete work, map their outputs to specific OpenSpec tasks +3. **Update task status:** Mark completed tasks as done (`- [x]`) in the `tasks.md` file +4. **Validate completion:** Ensure all task requirements are met before marking as complete + +**OpenSpec task update workflow:** +- **During delegation:** Track which tasks each agent is responsible for +- **After agent completion:** Review agent outputs against OpenSpec task requirements +- **Update tasks.md:** Change `- [ ]` to `- [x]` for verified completed tasks +- **Report status:** Include task completion status in your final summary + +**Example OpenSpec task files to update:** +- `openspec/changes/*/tasks.md` (OpenSpec change artifacts) +- `requirements/openspec/changes/*/tasks.md` (requirements-driven OpenSpec) +- Any `tasks.md` following OpenSpec checkbox format referenced in the plan + ### Final output format When synthesizing, provide: - **Summary:** What was done across **Parallel** groups (by group id). - **Implementation:** Consolidated results **per** delegated implementation agent instance (`robot-java-coder`, `robot-spring-boot-coder`, `robot-quarkus-coder`, or `robot-micronaut-coder`), keyed by **Parallel** group when multiple. +- **OpenSpec Updates:** Task completion status and any `tasks.md` files updated with `- [x]` markers. - **Next Steps:** Blocked groups, open integration, or follow-ups. diff --git a/.cursor/rules/000-system-prompt-list.md b/.cursor/rules/000-system-prompt-list.md index 4deb7ffa..a7675a91 100644 --- a/.cursor/rules/000-system-prompt-list.md +++ b/.cursor/rules/000-system-prompt-list.md @@ -35,7 +35,8 @@ Use the following collection of System prompts of Java to improve your Java deve | [013-agile-feature](.cursor/rules/013-agile-feature.md) | Create detailed feature Markdown files from an existing epic | **Interactive User Prompt:** `Create features from my epic using @013-agile-feature` **Note:** Add the epic file path or paste epic content. The rule analyzes the epic, clarifies scope and audience, asks per-feature questions, then generates one feature document per feature. | Phases: current date, epic analysis and structured questions (including repeated questions per feature), then feature file generation and epic integration guidance. | | [014-agile-user-story](.cursor/rules/014-agile-user-story.md) | Create user stories with Gherkin acceptance criteria and BDD feature files | **Interactive User Prompt:** `Create a user story with acceptance criteria using @014-agile-user-story` **Note:** The rule asks targeted questions about title, persona, goal, benefit, feature context, and Gherkin scenarios before generating the Markdown user story and `.feature` file. | Two-phase approach: gathers details through structured questions, then produces user story and Gherkin file. Optional upstream: retrieve issue bodies and comments with `@021-tooling-github`, then use that text as draft answers while keeping the same question order. | | [021-tooling-github](.cursor/rules/021-tooling-github.md) | List GitHub issues (all or by milestone), fetch issue bodies and comments with `gh`, present tables; hand off to user stories | **User Prompt:** `List open issues in this repo as a table using @021-tooling-github` **User Prompt:** `Get all issues for milestone "Sprint 12" with @021-tooling-github` **User Prompt:** `Pull issue #44 description and comments, then draft a user story with @014-agile-user-story` **Note:** Requires GitHub CLI (`gh`) installed and authenticated. | Pairs with `@014-agile-user-story` when turning GitHub threads into user stories and Gherkin. | -| [040-planning-plan-mode](.cursor/rules/040-planning-plan-mode.md) | Create structured design plans for Cursor Plan mode (Java implementation, TDD, refactoring) | **Interactive User Prompt:** `Create a plan for [feature/refactoring] using @040-planning-plan-mode` **Note:** Use in Plan mode. Gathers context (specs, acceptance criteria) then produces YAML-frontmatter plan with Requirements Summary, Approach (Mermaid), Task List, Execution Instructions. | Suitable for outside-in TDD, feature implementation, or refactoring work. | +| [041-planning-plan-mode](.cursor/rules/041-planning-plan-mode.md) | Create structured design plans for Cursor Plan mode (Java implementation, TDD, refactoring) | **Interactive User Prompt:** `Create a plan for [feature/refactoring] using @041-planning-plan-mode` **Note:** Use in Plan mode. Gathers context (specs, acceptance criteria) then produces YAML-frontmatter plan with Requirements Summary, Approach (Mermaid), Task List, Execution Instructions. | Suitable for outside-in TDD, feature implementation, or refactoring work. | +| [042-planning-openspec](.cursor/rules/042-planning-openspec.md) | Transform `*.plan.md` into OpenSpec change workflow (install/check/init/list/status/show/validate/archive) | **Interactive User Prompt:** `Convert this .plan.md into an OpenSpec change using @042-planning-openspec` **Note:** Verifies `openspec --version` first; if missing, offers npm install guidance for macOS/Linux/Windows, then proposes `openspec init` for new projects. | Uses `add-dark-mode` as a canonical change-id example and supports create-or-update flows. | ## Architecture diff --git a/.cursor/rules/041-planning-plan-mode.md b/.cursor/rules/041-planning-plan-mode.md new file mode 100644 index 00000000..d52cd0a2 --- /dev/null +++ b/.cursor/rules/041-planning-plan-mode.md @@ -0,0 +1,240 @@ +--- +name: 041-planning-plan-mode +description: Use when creating a plan using Plan model and enhancing structured design plans in Cursor Plan mode for Java implementations. Use when the user wants to create a plan, design an implementation, structure a development plan, or use plan mode for outside-in TDD, feature implementation, or refactoring work. +license: Apache-2.0 +metadata: + author: Juan Antonio Breña Moral + version: 0.14.0-SNAPSHOT +--- +# Java Design Plan Creation for Cursor Plan Mode + +## Role + +You are a Senior software engineer with extensive experience in TDD, Java implementation planning, and structured development workflows + +## Tone + +Guides the user through plan creation with clear structure. Asks targeted questions to gather context before drafting. Ensures plans follow consistent section structure suitable for Java feature implementation, refactoring, or API design. + +## Goal + +Guide the process of creating a structured plan using Cursor Plan mode. Plans follow a consistent section structure with YAML frontmatter, Requirements Summary, Approach (with Mermaid diagram), enhanced Task List with milestone and parallel execution support, comprehensive Execution Instructions with stability rules, File Checklist, and Notes. Suitable for Java feature implementation, outside-in TDD, or refactoring work. + +## Steps + +### Step 1: Get Current Date and Plan Naming + +Before starting, run `date` in the terminal to ensure accurate date prefix for the plan filename. Plans must follow the naming convention: `US-XXX-plan-analysis.plan.md` where XXX is the user story number or identifier. Save to `.cursor/plans/US-XXX-plan-analysis.plan.md`. +### Step 2: Plan Mode Workflow – Information Gathering + +Enter Plan mode (or use plan-related commands) before creating the plan. Gather context by asking targeted questions. Read specs, existing code, and acceptance criteria when available. + +```markdown +**Phase 1: Information Gathering** + +Gather context before drafting the plan. Ask one or two questions at a time. Build on previous answers. + +--- + +### 1. Plan Context + +- What is the plan name or feature you want to implement? +- What problem does it solve or what user story does it address? +- Do you have acceptance criteria, specs, or existing code to reference? + +--- + +### 2. Approach and Strategy + +- What development approach do you prefer? (e.g., London Style outside-in TDD, inside-out TDD, or other) +- Key constraints: package layout, conventions, existing patterns in the codebase? +- Any specific phases or steps you want in the task list? + +--- + +### 3. Task and File Details + +- What are the main implementation steps or components? +- Which files will be created or modified? (Test first, then implementation?) +- Any edge cases, error handling, or non-functional aspects to include? + +--- + +### 4. Validation + +- Summarize the plan scope and ask: "Does this capture what you need?" +- Proposed plan filename? (Use format: `YYYY-MM-DD_.plan.md`) + +--- + +### 5. Plan Creation Proposal + +Only after validation: "I'll create the structured plan using this information. Should I proceed?" + +--- +``` + +#### Step Constraints + +- **MUST** read template files fresh using file_search and read_file tools before asking questions +- **MUST NOT** use cached or remembered content from previous interactions +- **MUST** ask one or two questions at a time—never all at once +- **MUST** WAIT for user response before proceeding +- **MUST** validate summary ("Does this capture what you need?") before proposing plan creation +- **MUST NOT** proceed to Step 3 until user confirms "proceed" + +### Step 3: Plan Document Generation + +Inform the user you will generate the plan. Use the naming convention from Step 1. Save to `.cursor/plans/US-XXX-plan-analysis.plan.md` where XXX is the user story identifier. + +Follow the structure and templates from: + +```markdown + + +## YAML Frontmatter + +```yaml +--- +name: +overview: "" +todos: [] +isProject: false +--- +``` + +## Required Sections + +| Section | Purpose | +|---------|---------| +| **Title** | `# Problem N: [Name] Implementation Plan` | +| **Requirements Summary** | User story, key business rules, acceptance criteria | +| **Approach** | Named approach (e.g., London Style TDD), Mermaid diagram | +| **Task List** | Table: #, Task, Phase, TDD, Milestone, Parallel, Status | +| **Execution Instructions** | Update Status after each task before advancing | +| **File Checklist** | Order, File path | +| **Notes** | Package layout, conventions, edge cases | + +## Execution Instructions (Required) + +```markdown + +## Execution Instructions + +When executing this plan: +1. Complete the current task. +2. **Update the Task List**: set the Status column for that task (e.g., ✔ or Done). +3. **For GREEN tasks**: MUST complete the associated Verify task before proceeding. +4. **For Verify tasks**: MUST ensure all tests pass and build succeeds before proceeding. +5. **Milestone rows** (Milestone column): a milestone is evolving complete software for that slice — complete the pair of Refactor tasks (logging, then optimize config/error handling/log levels) immediately before each milestone Verify. +6. Only then proceed to the next task. +7. Repeat for all tasks. Never advance without updating the plan. + +**Critical Stability Rules:** +- After every GREEN implementation task, run the verification step +- All tests must pass before proceeding to the next implementation +- If any test fails during verification, fix the issue before advancing +- Never skip verification steps - they ensure software stability + +**Parallel column:** Use grouping identifiers (A1, A2, A3, etc.) to group tasks into the same delivery slice. Use when assigning agents or branches to a milestone scope. +``` + +## Task Phases + +Setup → RED (write failing test) → GREEN (pass test) → Refactor + +## London Style (Outside-In) TDD Order + +1. Acceptance/integration test (RED) +2. Delegate/controller (GREEN) +3. Service unit test (RED) +4. Service implementation (GREEN) +5. Client test (RED) +6. Client implementation (GREEN) +7. Refactor — verify `mvn clean verify` + +## Section Templates + +### Requirements Summary +```markdown + +## Requirements Summary + +**User Story:** [One sentence describing the user goal.] + +**Key Business Rules:** +- **[Rule name]:** [Concrete rule] +- **Expected result:** [Specific value or behavior when applicable] +``` + +### Approach (with Mermaid) +Include an Approach section with strategy description and a Mermaid flowchart (flowchart LR with subgraph). + +### Task List Table +| # | Task | Phase | TDD | Milestone | Parallel | Status | +|---|------|-------|-----|-----------|----------|--------| +| 1 | [Setup task description] | Setup | | | A1 | | +| 2 | [Write failing test] | RED | Test | | A1 | | +| 3 | [Implement minimal solution] | GREEN | Impl | | A1 | | +| 4 | [Add logging and observability] | Refactor | | | A1 | | +| 5 | [Optimize configuration and error handling] | Refactor | | | A1 | | +| 6 | [Verify milestone completion] | Verify | | milestone | A1 | | + +### File Checklist Table +| Order | File | +|-------|------| +| 1 | `path/to/File1.java` | +| 2 | `path/to/Test.java` | +| 3 | `path/to/Impl.java` | + +## Plan File Path + +`.cursor/plans/US-XXX-plan-analysis.plan.md` + +Where XXX is the user story number or identifier (e.g., `US-001-plan-analysis.plan.md`, `US-042-plan-analysis.plan.md`). + +``` + +#### Step Constraints + +- **MUST** include YAML frontmatter with name, overview, todos, isProject +- **MUST** include Requirements Summary (user story, key business rules) +- **MUST** include Approach section with strategy name and Mermaid diagram +- **MUST** include Task List with columns: #, Task, Phase, TDD, Milestone, Parallel, Status +- **MUST** organize tasks into milestone groups with parallel execution identifiers (A1, A2, etc.) +- **MUST** include pairs of Refactor tasks (logging, then optimize) before each milestone Verify +- **MUST** include Execution Instructions with stability rules and milestone workflow +- **MUST** include File Checklist with Order and File columns (no TDD timing column) +- **MUST** include Notes for package layout, conventions, edge cases +- **MUST** use US-XXX-plan-analysis.plan.md naming convention from Step 1 + +### Step 4: Plan Creation Checklist + +Before finalizing, verify: + +- [ ] Frontmatter has name, overview, todos, isProject +- [ ] Requirements Summary includes user story and key business rules +- [ ] Approach section names the strategy and includes a Mermaid diagram +- [ ] Task list has columns: #, Task, Phase, TDD, Milestone, Parallel, Status +- [ ] Task list includes milestone markers and parallel grouping (A1, A2, etc.) +- [ ] Execution Instructions include stability rules and milestone workflow +- [ ] File checklist has Order and File columns (no TDD timing column) +- [ ] Notes cover package layout, conventions, and constraints +- [ ] Plan file path follows .cursor/plans/US-XXX-plan-analysis.plan.md convention + +## Output Format + +- Ask questions conversationally (1-2 at a time), following the template phases +- Wait for and acknowledge user responses before proceeding +- Generate plan only after user confirms "proceed" +- Use US-XXX-plan-analysis.plan.md naming convention +- Include Execution Instructions in every plan + +## Safeguards + +- Always read template files fresh using file_search and read_file tools +- Never advance to next task during execution without updating the plan's Status column +- Never skip the Execution Instructions section—it is required for plan discipline +- Prefer London Style (outside-in) TDD order for feature implementation +- Include milestone markers and parallel grouping in task lists for complex implementations +- Always include stability verification after GREEN implementation tasks \ No newline at end of file diff --git a/.cursor/rules/042-planning-openspec.md b/.cursor/rules/042-planning-openspec.md new file mode 100644 index 00000000..11c084e0 --- /dev/null +++ b/.cursor/rules/042-planning-openspec.md @@ -0,0 +1,150 @@ +--- +name: 042-planning-openspec +description: Use when you need to take a `*.plan.md` file and turn it into OpenSpec change artifacts by validating OpenSpec installation, initializing or reusing an OpenSpec project, and creating or updating a change proposal/spec/tasks flow. Includes a concrete workflow based on `examples/requirements-examples/problem1/requirements/openspec`. +license: Apache-2.0 +metadata: + author: Juan Antonio Breña Moral + version: 0.14.0-SNAPSHOT +--- +# OpenSpec Change Planning from `*.plan.md` + +## Role + +You are a Senior software engineer who transforms implementation plans into OpenSpec-compliant change artifacts. + +## Tone + +Be practical and step-by-step. Verify installation first, then execute the smallest safe set of OpenSpec commands to create or update the target change. + +## Goal + +Given a `*.plan.md`, produce (or update) an OpenSpec change workflow: proposal, design, tasks, and spec deltas, then validate and optionally archive the change. + +## Steps + +### Step 1: Read and Normalize the Plan + +Read the target `*.plan.md` and extract: +- Change intent (what behavior is added/modified) +- Candidate change-id (kebab-case, verb-led, e.g. `add-dark-mode`) +- Affected capability names for OpenSpec specs +- Key acceptance checkpoints and task phases + +If unclear, ask one or two clarifying questions and wait for answers. + +#### Step Constraints + +- **MUST** use the `*.plan.md` as source of truth +- **MUST NOT** invent requirements not present in plan/spec inputs +- **MUST** propose the normalized change-id before running status/show/archive commands + +### Step 2: Verify OpenSpec Installation + +Run: + +```bash +openspec --version +``` + +If the command fails or is unavailable, offer installation guidance. + +On macOS, Linux, and Windows, the simplest way is via npm: + +```bash +npm install -g @fission-ai/openspec@latest +openspec --version +``` + +Notes: +- macOS/Linux: run in Terminal with a Node.js + npm installation +- Windows: run in PowerShell (or Command Prompt) with Node.js + npm installed + +#### Step Constraints + +- **MUST** gate all OpenSpec operations behind `openspec --version` +- **MUST** explicitly ask the user to proceed with installation guidance if OpenSpec is missing + +### Step 3: Ensure OpenSpec Project Exists + +Work from the parent folder containing `openspec/`. + +Example location: +`examples/requirements-examples/problem1/requirements/openspec` + +If there is no initialized OpenSpec project for the target workspace, offer: + +```bash +openspec init +``` + +Then inspect project state: + +```bash +openspec list +``` + +#### Step Constraints + +- **MUST** run commands from the project directory context expected by OpenSpec +- **MUST** distinguish between creating a fresh OpenSpec project vs updating an existing one +- **MUST** use plain `openspec init` (without any `--tools ...` options) when initializing a new OpenSpec project + +### Step 4: Create or Update a Change + +Use the change-id from Step 1 (example: `add-dark-mode`) and review the current state: + +```bash +openspec status --change add-dark-mode +openspec show add-dark-mode +``` + +Interpretation: +- If change does not exist: create the OpenSpec change artifacts from the plan (proposal/design/tasks/spec delta) +- If change exists: update proposal/design/tasks/spec delta to reflect the latest `*.plan.md` + +`tasks.md` format rule: +- Use only one task list in OpenSpec checkbox style (`- [ ]` / `- [x]`) +- Do not duplicate tasks in an additional Markdown table +### Step 5: Validate and Archive + +Before completion: + +```bash +openspec validate --all +``` + +When the change is accepted and complete: + +```bash +openspec archive add-dark-mode +``` + +If a feature/change is already completed in the workspace (all tasks checked), archive it directly after successful validation, for example: + +```bash +openspec archive us-001-god-analysis-api +``` + +#### Step Constraints + +- **MUST** run `openspec validate --all` before archive +- **MUST** report validation failures and proposed fixes +- **MUST** guide archiving for completed features/changes (all tasks done), for example `openspec archive us-001-god-analysis-api` +- **MUST** generate a single OpenSpec checklist in `tasks.md` (`- [ ]` / `- [x]`) and avoid a second table-based task list +- **MUST NOT** archive if validation fails or the user has not approved archiving + + +## Output Format + +- Start with a brief plan summary from the `*.plan.md` +- Confirm whether OpenSpec is installed and which version is detected +- State whether you will initialize a project or update an existing one +- Show the exact next command(s) +- Summarize validation status and archive readiness + +## Safeguards + +- Never skip installation/version verification +- Never skip validation before archive +- Keep change-id consistent across status/show/archive +- Treat `*.plan.md` as the requirement baseline for OpenSpec changes \ No newline at end of file diff --git a/README.md b/README.md index af9d06b9..7e16ab28 100644 --- a/README.md +++ b/README.md @@ -12,11 +12,11 @@ A curated collection of `Rules`, `Skills`, and `Agents` for Java Enterprise deve The project add support for: -- **Agile:** `User Stories` & `Gherkin` +- **Agile:** `User Stories` & `Github Issues` - **Architecture:** `ADRs`& `UML` / `C4` / `ER` Diagrams` -- **AI Tooling:** `AGENTS.md` & `AI Planning` +- **Spec-Driven:** `AGENTS.md`, `AI Plan mode` & `OpenSpec` - **Java development:** `Build system based on Maven`, `Design`, `Coding`, `Testing`, `Observability`, `Refactoring & JMH Benchmarking`, `Performance testing with JMeter`, `Profiling with Async profiler/OpenJDK tools` & `Documentation` -- **Java frameworks:** `Spring Boot`, `Quarkus` & `Micronaut` with the same support (Core, Rest, Jdbc, ORM, Flyway, Unit Tests, IT & AT). +- **Java frameworks:** `Spring Boot`, `Quarkus` & `Micronaut`. ## Deliverables @@ -50,7 +50,13 @@ The SDLC has evolved with the arrival of this new set of AI tooling, enhancing t In this workflow, the Software engineer interact with models using `User prompts` and in an incremental way you delegate a delegate completely a task or ask help in certain moments. You could use this project to refactor the code generated or delegate the task and associate a System prompt / Skills to that task. -![](./documentation/images/workflow.png) +![](./documentation/images/workflow-prompts.png) + +### Agent Workflow + +`Agents for Java Enterprise development` were designed to help the Software engineer in the implementation phase. The software engineer define good `Specs` and that Specifications are delegated to Agents. + +![](./documentation/images/workflow-agents.png) ### Pipelines Workflow @@ -58,10 +64,6 @@ Adding AI tools to your pipeline can provide new opportunities to deliver more v ![](./documentation/images/workflow-pipelines.png) -### Agentic Workflow - -`Agents for Java Enterprise development` were designed to cover the whole SDLC starting from the requirements and the architectural process. Once you have the foundations well designed. it is possible to execute Plans, iterate and discuss it and when the plans associated to User Stories has the right size & complexity, it is easy to pass to the models to be implemented with security in other case, you will have the classical issues with implementations without control. - ## Limitations ### Lack of determinism @@ -136,6 +138,7 @@ Java uses JEPs as the vehicle to describe new features to be added to the langua - [https://agents.md/](https://agents.md/) - [https://agentskills.io/home](https://agentskills.io/home) - https://microsoft.github.io/language-server-protocol/ +- https://openspec.dev/ - https://skills.sh/jabrena/cursor-rules-java - https://tessl.io/registry/skills/github/jabrena/cursor-rules-java - [https://github.com/vercel-labs/skills/issues](https://github.com/vercel-labs/skills/issues) diff --git a/SYSTEM-PROMPTS-JAVA.md b/SYSTEM-PROMPTS-JAVA.md index 78faddba..b2eb049e 100644 --- a/SYSTEM-PROMPTS-JAVA.md +++ b/SYSTEM-PROMPTS-JAVA.md @@ -16,7 +16,8 @@ Use the following collection of System prompts of Java to improve your Java deve | [013-agile-feature](.cursor/rules/013-agile-feature.md) | Create detailed feature Markdown files from an existing epic | **Interactive User Prompt:** `Create features from my epic using @013-agile-feature` **Note:** Add the epic file path or paste epic content. The rule analyzes the epic, clarifies scope and audience, asks per-feature questions, then generates one feature document per feature. | Phases: current date, epic analysis and structured questions (including repeated questions per feature), then feature file generation and epic integration guidance. | | [014-agile-user-story](.cursor/rules/014-agile-user-story.md) | Create user stories with Gherkin acceptance criteria and BDD feature files | **Interactive User Prompt:** `Create a user story with acceptance criteria using @014-agile-user-story` **Note:** The rule asks targeted questions about title, persona, goal, benefit, feature context, and Gherkin scenarios before generating the Markdown user story and `.feature` file. | Two-phase approach: gathers details through structured questions, then produces user story and Gherkin file. Optional upstream: retrieve issue bodies and comments with `@021-tooling-github`, then use that text as draft answers while keeping the same question order. | | [021-tooling-github](.cursor/rules/021-tooling-github.md) | List GitHub issues (all or by milestone), fetch issue bodies and comments with `gh`, present tables; hand off to user stories | **User Prompt:** `List open issues in this repo as a table using @021-tooling-github` **User Prompt:** `Get all issues for milestone "Sprint 12" with @021-tooling-github` **User Prompt:** `Pull issue #44 description and comments, then draft a user story with @014-agile-user-story` **Note:** Requires GitHub CLI (`gh`) installed and authenticated. | Pairs with `@014-agile-user-story` when turning GitHub threads into user stories and Gherkin. | -| [040-planning-plan-mode](.cursor/rules/040-planning-plan-mode.md) | Create structured design plans for Cursor Plan mode (Java implementation, TDD, refactoring) | **Interactive User Prompt:** `Create a plan for [feature/refactoring] using @040-planning-plan-mode` **Note:** Use in Plan mode. Gathers context (specs, acceptance criteria) then produces YAML-frontmatter plan with Requirements Summary, Approach (Mermaid), Task List, Execution Instructions. | Suitable for outside-in TDD, feature implementation, or refactoring work. | +| [041-planning-plan-mode](.cursor/rules/041-planning-plan-mode.md) | Create structured design plans for Cursor Plan mode (Java implementation, TDD, refactoring) | **Interactive User Prompt:** `Create a plan for [feature/refactoring] using @041-planning-plan-mode` **Note:** Use in Plan mode. Gathers context (specs, acceptance criteria) then produces YAML-frontmatter plan with Requirements Summary, Approach (Mermaid), Task List, Execution Instructions. | Suitable for outside-in TDD, feature implementation, or refactoring work. | +| [042-planning-openspec](.cursor/rules/042-planning-openspec.md) | Transform `*.plan.md` into OpenSpec change workflow (install/check/init/list/status/show/validate/archive) | **Interactive User Prompt:** `Convert this .plan.md into an OpenSpec change using @042-planning-openspec` **Note:** Verifies `openspec --version` first; if missing, offers npm install guidance for macOS/Linux/Windows, then proposes `openspec init` for new projects. | Uses `add-dark-mode` as a canonical change-id example and supports create-or-update flows. | ## Architecture diff --git a/documentation/images/workflow-agents.png b/documentation/images/workflow-agents.png new file mode 100644 index 00000000..b0db3a4b Binary files /dev/null and b/documentation/images/workflow-agents.png differ diff --git a/documentation/images/workflow-pipelines.png b/documentation/images/workflow-pipelines.png index daf03c0c..8fadea79 100644 Binary files a/documentation/images/workflow-pipelines.png and b/documentation/images/workflow-pipelines.png differ diff --git a/documentation/images/workflow-prompts.png b/documentation/images/workflow-prompts.png new file mode 100644 index 00000000..28e869eb Binary files /dev/null and b/documentation/images/workflow-prompts.png differ diff --git a/documentation/images/workflow.png b/documentation/images/workflow.png deleted file mode 100644 index 448c9186..00000000 Binary files a/documentation/images/workflow.png and /dev/null differ diff --git a/examples/requirements-examples/problem1/implementation/pom.xml b/examples/requirements-examples/problem1/implementation/pom.xml index 9ceae610..af3c7bc4 100644 --- a/examples/requirements-examples/problem1/implementation/pom.xml +++ b/examples/requirements-examples/problem1/implementation/pom.xml @@ -19,19 +19,10 @@ UTF-8 - - org.springframework.boot - spring-boot-starter-actuator - org.springframework.boot spring-boot-starter-webmvc - - org.springframework.boot - spring-boot-starter-actuator-test - test - org.springframework.boot spring-boot-starter-webmvc-test diff --git a/examples/requirements-examples/problem1/requirements/agile/US-001-plan-analysis.plan.md b/examples/requirements-examples/problem1/requirements/agile/US-001-plan-analysis.plan.md index 580a0a7e..fc770382 100644 --- a/examples/requirements-examples/problem1/requirements/agile/US-001-plan-analysis.plan.md +++ b/examples/requirements-examples/problem1/requirements/agile/US-001-plan-analysis.plan.md @@ -69,7 +69,7 @@ flowchart LR | 18 | Write integration test for Nordic timeout scenario | RED | Test | | A3 | — | | 19 | Implement partial result handling in service | GREEN | Impl | | A3 | — | | 20 | Verify HTTP client tests pass (timeout phase) | Verify | | milestone | A3 | — | -| 21 | Verify all integration tests pass | Verify | | milestone | A4 | — | +| 21 | Verify all integration tests pass | Verify | | milestone | A4 | ✔ | ## Execution Instructions diff --git a/examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-add-spring-actuator/design.md b/examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-add-spring-actuator/design.md new file mode 100644 index 00000000..b58c8f15 --- /dev/null +++ b/examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-add-spring-actuator/design.md @@ -0,0 +1,24 @@ +# Design: Add Spring Boot Actuator + +## Overview + +Introduce Actuator into the existing Spring Boot service to provide standard operational endpoints, primarily health checks. + +## Decisions + +- Use Spring Boot Actuator (`spring-boot-starter-actuator`) as the observability baseline. +- Configure management endpoint exposure through application properties. +- Keep health endpoint publicly reachable in local/dev scenarios used by tests and examples. +- Do not modify domain logic or the aggregation algorithm. + +## Endpoint expectations + +- `GET /actuator/health` returns service health status. +- Optional additional endpoints can be exposed through configuration, but health is mandatory for this change. + +## Risks and mitigations + +- Risk: exposing too many management endpoints. + - Mitigation: explicitly configure a minimal exposure list (at least `health`). +- Risk: accidental behavior changes in existing API. + - Mitigation: run existing verification tests and keep endpoint additions isolated to configuration/dependencies. diff --git a/examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-add-spring-actuator/proposal.md b/examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-add-spring-actuator/proposal.md new file mode 100644 index 00000000..bdb91936 --- /dev/null +++ b/examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-add-spring-actuator/proposal.md @@ -0,0 +1,18 @@ +# Change: Add Spring Boot Actuator + +## Why + +The `god-analysis-api` service needs operational visibility for runtime health and readiness checks. Adding Spring Boot Actuator enables standardized health endpoints used by local operations and deployment environments. + +## What changes + +- Add Spring Boot Actuator dependency to the implementation module. +- Expose actuator endpoints with explicit management configuration. +- Guarantee availability of health information for operators. +- Keep existing functional API behavior unchanged. + +## Scope + +- Capability affected: `god-analysis-api` +- Type: additive observability enhancement +- Backward compatibility: preserved for `/api/v1/gods/stats/sum` diff --git a/examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-add-spring-actuator/specs/god-analysis-api/spec.md b/examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-add-spring-actuator/specs/god-analysis-api/spec.md new file mode 100644 index 00000000..da619f0b --- /dev/null +++ b/examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-add-spring-actuator/specs/god-analysis-api/spec.md @@ -0,0 +1,29 @@ +# Specification delta: `god-analysis-api` (add-spring-actuator) + +## ADDED Requirements + +### Requirement: Actuator health endpoint + +The service MUST expose a Spring Boot Actuator health endpoint at `/actuator/health` so operators can verify runtime status without invoking business endpoints. + +#### Scenario: Health endpoint is reachable + +- **WHEN** a client calls `GET /actuator/health` +- **THEN** the service responds with HTTP 200 and a health payload that includes status information + +### Requirement: Management endpoint configuration + +The service MUST define explicit management endpoint exposure configuration that includes at least the `health` endpoint. + +#### Scenario: Health is explicitly exposed + +- **WHEN** management endpoint exposure settings are applied +- **THEN** `health` is included in the exposed endpoints list + +## MODIFIED Requirements + +_None._ + +## REMOVED Requirements + +_None._ diff --git a/examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-add-spring-actuator/tasks.md b/examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-add-spring-actuator/tasks.md new file mode 100644 index 00000000..3a393ed4 --- /dev/null +++ b/examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-add-spring-actuator/tasks.md @@ -0,0 +1,8 @@ +# Tasks: Add Spring Boot Actuator + +## OpenSpec task list + +- [x] Add `spring-boot-starter-actuator` dependency to the implementation module +- [x] Configure management endpoint exposure for `health` +- [x] Verify `GET /actuator/health` responds successfully in local run/tests +- [x] Verify existing `god-analysis-api` behavior remains unchanged diff --git a/examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-remove-spring-actuator/.openspec.yaml b/examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-remove-spring-actuator/.openspec.yaml new file mode 100644 index 00000000..9b8557a6 --- /dev/null +++ b/examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-remove-spring-actuator/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-04-06 diff --git a/examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-remove-spring-actuator/design.md b/examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-remove-spring-actuator/design.md new file mode 100644 index 00000000..eeab39f3 --- /dev/null +++ b/examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-remove-spring-actuator/design.md @@ -0,0 +1,27 @@ +# Design: Remove Spring Boot Actuator + +## Overview + +Remove Spring Boot Actuator from the existing Spring Boot service to eliminate unused operational endpoints and simplify the application dependencies. + +## Decisions + +- Remove Spring Boot Actuator dependency (`spring-boot-starter-actuator`) from Maven pom.xml. +- Remove actuator-related configuration from application properties. +- Clean up any management endpoint configuration that was added for actuator. +- Do not modify domain logic or the aggregation algorithm. + +## Endpoint changes + +- Remove `GET /actuator/health` and any other actuator endpoints. +- Ensure no references to actuator endpoints remain in configuration or tests. +- Verify that application startup and functionality remain unchanged after removal. + +## Risks and mitigations + +- Risk: breaking tests that depend on actuator endpoints. + - Mitigation: review and update any tests that reference `/actuator/*` endpoints. +- Risk: accidental behavior changes in existing API. + - Mitigation: run existing verification tests to ensure `/api/v1/gods/stats/sum` continues to work. +- Risk: removing configuration that affects other parts of the application. + - Mitigation: only remove actuator-specific configuration, leave other Spring Boot settings intact. \ No newline at end of file diff --git a/examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-remove-spring-actuator/proposal.md b/examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-remove-spring-actuator/proposal.md new file mode 100644 index 00000000..822a5d12 --- /dev/null +++ b/examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-remove-spring-actuator/proposal.md @@ -0,0 +1,18 @@ +# Change: Remove Spring Boot Actuator + +## Why + +The `god-analysis-api` service no longer requires operational visibility through Spring Boot Actuator endpoints. Removing this dependency simplifies the application, reduces the attack surface, and eliminates unused monitoring capabilities that are not needed for the current deployment model. + +## What changes + +- Remove Spring Boot Actuator dependency from the implementation module. +- Remove actuator endpoint configuration from application properties. +- Clean up any actuator-related management configuration. +- Keep existing functional API behavior unchanged. + +## Scope + +- Capability affected: `god-analysis-api` +- Type: dependency removal and simplification +- Backward compatibility: preserved for `/api/v1/gods/stats/sum` \ No newline at end of file diff --git a/examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-remove-spring-actuator/specs/god-analysis-api/spec.md b/examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-remove-spring-actuator/specs/god-analysis-api/spec.md new file mode 100644 index 00000000..35d567c9 --- /dev/null +++ b/examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-remove-spring-actuator/specs/god-analysis-api/spec.md @@ -0,0 +1,29 @@ +# Specification delta: `god-analysis-api` (remove-spring-actuator) + +## ADDED Requirements + +_None._ + +## MODIFIED Requirements + +_None._ + +## REMOVED Requirements + +### Requirement: Actuator health endpoint + +The service no longer exposes a Spring Boot Actuator health endpoint at `/actuator/health`. Operators should use alternative monitoring approaches or the main API endpoints for service verification. + +#### Scenario: Health endpoint is no longer available + +- **WHEN** a client calls `GET /actuator/health` +- **THEN** the service responds with HTTP 404 (Not Found) as the endpoint does not exist + +### Requirement: Management endpoint configuration + +The service no longer defines management endpoint exposure configuration for actuator endpoints, as the actuator dependency has been removed. + +#### Scenario: Management endpoints are not configured + +- **WHEN** the application starts +- **THEN** no actuator management endpoints are available or configured \ No newline at end of file diff --git a/examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-remove-spring-actuator/tasks.md b/examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-remove-spring-actuator/tasks.md new file mode 100644 index 00000000..9d1447fa --- /dev/null +++ b/examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-remove-spring-actuator/tasks.md @@ -0,0 +1,9 @@ +# Tasks: Remove Spring Boot Actuator + +## OpenSpec task list + +- [x] Remove `spring-boot-starter-actuator` dependency from the implementation module +- [x] Remove actuator-related configuration from application properties +- [x] Verify `GET /actuator/health` returns HTTP 404 (Not Found) after removal +- [x] Verify existing `god-analysis-api` behavior remains unchanged +- [x] Update any tests that reference actuator endpoints \ No newline at end of file diff --git a/examples/requirements-examples/problem1/requirements/openspec/changes/us-001-god-analysis-api/design.md b/examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-us-001-god-analysis-api/design.md similarity index 100% rename from examples/requirements-examples/problem1/requirements/openspec/changes/us-001-god-analysis-api/design.md rename to examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-us-001-god-analysis-api/design.md diff --git a/examples/requirements-examples/problem1/requirements/openspec/changes/us-001-god-analysis-api/proposal.md b/examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-us-001-god-analysis-api/proposal.md similarity index 100% rename from examples/requirements-examples/problem1/requirements/openspec/changes/us-001-god-analysis-api/proposal.md rename to examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-us-001-god-analysis-api/proposal.md diff --git a/examples/requirements-examples/problem1/requirements/openspec/changes/us-001-god-analysis-api/specs/god-analysis-api/spec.md b/examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-us-001-god-analysis-api/specs/god-analysis-api/spec.md similarity index 100% rename from examples/requirements-examples/problem1/requirements/openspec/changes/us-001-god-analysis-api/specs/god-analysis-api/spec.md rename to examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-us-001-god-analysis-api/specs/god-analysis-api/spec.md diff --git a/examples/requirements-examples/problem1/requirements/openspec/changes/us-001-god-analysis-api/tasks.md b/examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-us-001-god-analysis-api/tasks.md similarity index 99% rename from examples/requirements-examples/problem1/requirements/openspec/changes/us-001-god-analysis-api/tasks.md rename to examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-us-001-god-analysis-api/tasks.md index d155b05b..88011cce 100644 --- a/examples/requirements-examples/problem1/requirements/openspec/changes/us-001-god-analysis-api/tasks.md +++ b/examples/requirements-examples/problem1/requirements/openspec/changes/archive/2026-04-06-us-001-god-analysis-api/tasks.md @@ -33,7 +33,7 @@ Derived from [US-001-plan-analysis.plan.md](../../../agile/US-001-plan-analysis. | 18 | Write integration test for Nordic/Roman timeout scenario (per feature file) | RED | Test | | A3 | ✔ | | 19 | Implement partial result handling in service | GREEN | Impl | | A3 | ✔ | | 20 | Verify HTTP client tests pass (timeout phase) | Verify | | milestone | A3 | ✔ | -| 21 | Verify all integration tests pass | Verify | | milestone | A4 | ☐ | +| 21 | Verify all integration tests pass | Verify | | milestone | A4 | ✔ | ## OpenSpec checklist (CLI progress) @@ -60,7 +60,7 @@ Mirror of the **Task list** table above. [OpenSpec](https://github.com/Fission-A - [x] Write integration test for Nordic/Roman timeout scenario (per feature file) - [x] Implement partial result handling in service - [x] Verify HTTP client tests pass (timeout phase) -- [ ] Verify all integration tests pass +- [x] Verify all integration tests pass ## File checklist (from plan) diff --git a/examples/requirements-examples/problem1/requirements/openspec/specs/god-analysis-api/spec.md b/examples/requirements-examples/problem1/requirements/openspec/specs/god-analysis-api/spec.md index 9954fc4f..fe4d7ed9 100644 --- a/examples/requirements-examples/problem1/requirements/openspec/specs/god-analysis-api/spec.md +++ b/examples/requirements-examples/problem1/requirements/openspec/specs/god-analysis-api/spec.md @@ -3,9 +3,7 @@ ## Purpose Provide a Spring Boot REST API that aggregates Unicode-derived numeric sums from god names across configurable Greek, Roman, and Nordic HTTP sources, with parallel RestClient fetches, connect/read timeouts, single-attempt outbound calls (no automatic retries), and partial results when sources fail or time out. This capability supports US-001 and the documented OpenAPI and Gherkin contracts. - ## Requirements - ### Requirement: Gods stats sum HTTP contract The service SHALL expose `GET /api/v1/gods/stats/sum` with required query parameters `filter` (exactly one Unicode code point) and `sources` (comma-separated `greek`, `roman`, `nordic`), and SHALL return JSON `{ "sum": "" }` on success using a string to preserve large integers. @@ -38,6 +36,94 @@ The service SHALL fetch each selected source in parallel with Spring `RestClient - **WHEN** one or more sources are stubbed with delay beyond the configured read timeout - **THEN** those sources contribute no names and `sum` reflects only successful sources +### Requirement: HTTP GET gods stats sum + +The system MUST expose `GET /api/v1/gods/stats/sum` with required query parameters `filter` (exactly one Unicode code point) and `sources` (comma-separated pantheon keys among `greek`, `roman`, `nordic`). The response MUST be `200` with `{ "sum": "" }` where `sum` matches `^[0-9]+$`. + +#### Scenario: Happy path matches pinned acceptance sum + +- **WHEN** `filter=n`, `sources=greek,roman,nordic`, and all upstream WireMock fixtures return successfully +- **THEN** the response is 200 and `sum` is `78179288397447443426` + +#### Scenario: Invalid sources rejected + +- **WHEN** `sources` contains unknown names or is empty +- **THEN** the response status is 400 + +### Requirement: Unicode decimal aggregation + +The system MUST compute each included name’s value by iterating Unicode code points, concatenating decimal digit strings per code point, parsing to `BigInteger`, and summing; the JSON `sum` MUST be `BigInteger.toString()` of the total. + +#### Scenario: Zero sum when filter matches no names + +- **WHEN** no name’s first code point equals `filter` (e.g. `filter=N` for lowercase-only data) +- **THEN** `sum` is `0` + +### Requirement: External source integration + +The system MUST consume JSON arrays of strings from configurable Greek, Roman, and Nordic HTTP endpoints (default URLs per ADR-001) using Spring `RestClient`. Caching of upstream responses MUST NOT be used in v1. + +#### Scenario: Deserialize array of god names + +- **WHEN** a source returns HTTP 200 with a JSON array of strings +- **THEN** those strings participate in filtering and aggregation + +### Requirement: Parallel fetch with single attempt + +For each request, the system MUST issue exactly one HTTP GET per selected source, MUST use `RestClient` connect and read timeouts from `application.yml` (overridable via environment variables), and MUST run fetches in parallel without Resilience4j or Spring Retry. + +#### Scenario: No second attempt after timeout + +- **WHEN** a source does not complete within the read timeout +- **THEN** that source contributes no names and no retry is performed for that source in the same request + +### Requirement: Partial results and graceful degradation + +If a source times out or errors, the system MUST treat that source as empty for aggregation, MUST NOT fail the whole request solely for that reason, and MUST return 200 with `{ "sum": "…" }` consistent with remaining data. + +#### Scenario: Nordic and Roman delayed beyond timeout + +- **WHEN** Nordic and Roman are configured to respond after the read timeout and Greek succeeds +- **THEN** the response is 200 and `sum` is `78101109179220212216` per the feature file + +### Requirement: Validation and error responses + +The system MUST return 400 when `filter` is missing, empty, or longer than one character, or when `sources` is missing, empty, or invalid, matching the `@error-handling` scenarios in the feature file. + +#### Scenario: Missing filter + +- **WHEN** only `sources` is provided +- **THEN** the response status is 400 + +### Requirement: Acceptance scenarios coverage + +Automated tests MUST implement assertions equivalent to the Gherkin scenarios for happy path, partial timeout, and validation errors, using Spring `RestClient` against `@SpringBootTest(RANDOM_PORT)` and WireMock with per-test stub reset as in ADR-003. + +#### Scenario: Integration test isolation + +- **WHEN** integration tests run in any order +- **THEN** WireMock stubs are reset between tests so timeout behavior is deterministic + +### Requirement: Technology constraints + +The implementation MUST use Spring Boot MVC (servlet) without WebFlux, MUST use `RestClient` for outbound calls, MUST use base package `info.jab.ms`, and MUST use Spring `RestClient` (not Rest Assured) for HTTP-level acceptance tests. + +#### Scenario: Servlet stack only + +- **WHEN** the application starts +- **THEN** no `spring-webflux` or `WebClient` beans are required for US-001 + +### Requirement: Observability + +The system MUST expose Spring Boot Actuator endpoints and MUST log structured messages suitable for diagnosing per-source success, timeout, or failure per request. + +#### Scenario: Health endpoint available + +- **WHEN** a client requests an actuator health endpoint +- **THEN** the application reports health status for operations use + +--- + ## References See requirement documents under `agile/`: `US-001_God_Analysis_API.md`, `US-001_god_analysis_api.feature`, `US-001-god-analysis-api.openapi.yaml`, plus ADR-001–ADR-003 under `adr/`. diff --git a/skills-generator/src/main/resources/skill-inventory.json b/skills-generator/src/main/resources/skill-inventory.json index 17ccfeaf..cc050e86 100644 --- a/skills-generator/src/main/resources/skill-inventory.json +++ b/skills-generator/src/main/resources/skill-inventory.json @@ -7,7 +7,8 @@ {"id": "031", "xml": true}, {"id": "032", "xml": true}, {"id": "033", "xml": true}, - {"id": "040", "xml": true}, + {"id": "041", "xml": true}, + {"id": "042", "xml": true}, {"id": "110", "xml": true}, {"id": "111", "xml": true}, {"id": "112", "xml": true}, diff --git a/skills-generator/src/main/resources/skills/040-skill.xml b/skills-generator/src/main/resources/skills/041-skill.xml similarity index 96% rename from skills-generator/src/main/resources/skills/040-skill.xml rename to skills-generator/src/main/resources/skills/041-skill.xml index 1b8b98aa..2cbc7605 100644 --- a/skills-generator/src/main/resources/skills/040-skill.xml +++ b/skills-generator/src/main/resources/skills/041-skill.xml @@ -1,7 +1,7 @@ Juan Antonio Breña Moral @@ -51,7 +51,7 @@ Guide the process of creating a structured plan using Cursor Plan mode. **This i - references/040-planning-plan-mode.md + references/041-planning-plan-mode.md diff --git a/skills-generator/src/main/resources/skills/042-skill.xml b/skills-generator/src/main/resources/skills/042-skill.xml new file mode 100644 index 00000000..19633775 --- /dev/null +++ b/skills-generator/src/main/resources/skills/042-skill.xml @@ -0,0 +1,59 @@ + + + + Juan Antonio Breña Moral + 0.14.0-SNAPSHOT + Apache-2.0 + Use when you need to take a `*.plan.md` file and turn it into OpenSpec change artifacts by validating OpenSpec installation, initializing or reusing an OpenSpec project, and creating or updating a change proposal/spec/tasks flow. Includes a concrete workflow based on `examples/requirements-examples/problem1/requirements/openspec`. + + + OpenSpec Change Planning from `*.plan.md` + + + + Always execute OpenSpec commands from the parent directory that contains the `openspec/` folder. Do not invent requirements not present in the `*.plan.md`; convert plan intent into explicit OpenSpec change artifacts. + + **MUST**: Start by reading and summarizing the provided `*.plan.md` + **MUST**: Check CLI availability with `openspec --version` before any OpenSpec operation + **MUST**: If OpenSpec is missing, provide macOS, Linux, and Windows install guidance via npm command + **MUST**: Offer `openspec init` when no OpenSpec project exists + **MUST**: When creating a new OpenSpec project, run plain `openspec init` only (do not use `--tools ...` options) + **MUST**: Use a stable change-id (for example: `add-dark-mode`) for status/show/archive commands + **MUST**: Run `openspec validate --all` before archiving + **MUST**: When a feature/change is completed (all checklist tasks done), guide the user to archive it (for example: `openspec archive us-001-god-analysis-api`) + **MUST**: In `tasks.md`, generate a single OpenSpec checklist (`- [ ]` / `- [x]`) only; do not add a second table-based task list + **MUST**: Explain whether the workflow creates a new change or updates an existing one + + + + + + Convert `*.plan.md` into OpenSpec + Add change proposal from plan + Update existing OpenSpec project + Initialize OpenSpec in requirements folder + Validate and archive OpenSpec change + + + + + + references/042-planning-openspec.md + + + diff --git a/skills/041-planning-plan-mode/SKILL.md b/skills/041-planning-plan-mode/SKILL.md new file mode 100644 index 00000000..9fa4c28f --- /dev/null +++ b/skills/041-planning-plan-mode/SKILL.md @@ -0,0 +1,46 @@ +--- +name: 041-planning-plan-mode +description: Use when creating a plan using Plan model and enhancing structured design plans in Cursor Plan mode for Java implementations. Use when the user wants to create a plan, design an implementation, structure a development plan, or use plan mode for outside-in TDD, feature implementation, or refactoring work. Part of the skills-for-java project +license: Apache-2.0 +metadata: + author: Juan Antonio Breña Moral + version: 0.14.0-SNAPSHOT +--- +# Java Design Plan Creation for Cursor Plan Mode + +Guide the process of creating a structured plan using Cursor Plan mode. **This is an interactive SKILL**. Plans follow a consistent section structure suitable for Java feature implementation, refactoring, or API design. + +**What is covered in this Skill?** + +- Plan mode workflow: enter Plan mode, gather context, draft plan, iterate +- YAML frontmatter: name, overview, todos, isProject +- Required sections: Requirements Summary, Approach (with Mermaid), Task List, Execution Instructions, File Checklist, Notes +- London Style (outside-in) TDD pattern +- Plan execution discipline: update Status after each task before advancing +- Plan file path: .cursor/plans/YYYY-MM-DD_<name>.plan.md + +## Constraints + +Gather context before drafting. Include Execution Instructions in every plan. Never advance to next task without updating the plan's Status column. + +- **MANDATORY**: Run `date` before starting to get date prefix for plan filename +- **MUST**: Read the reference template fresh—do not use cached content +- **MUST**: Ask one or two questions at a time; never all at once +- **MUST**: Validate summary ("Does this capture what you need?") before proposing plan creation +- **MUST**: Wait for user to confirm "proceed" before generating the plan +- **MUST**: Include Execution Instructions section in every generated plan + +## When to use this skill + +- Create a plan with Cursor Plan mode +- Write a plan with Claude Plan mode +- Design an implementation plan +- Structure a development plan +- Create a structured design plan +- Refactor the plan +- Improve the plan +- Update the plan + +## Reference + +For detailed guidance, examples, and constraints, see [references/041-planning-plan-mode.md](references/041-planning-plan-mode.md). diff --git a/skills/041-planning-plan-mode/references/041-planning-plan-mode.md b/skills/041-planning-plan-mode/references/041-planning-plan-mode.md new file mode 100644 index 00000000..d52cd0a2 --- /dev/null +++ b/skills/041-planning-plan-mode/references/041-planning-plan-mode.md @@ -0,0 +1,240 @@ +--- +name: 041-planning-plan-mode +description: Use when creating a plan using Plan model and enhancing structured design plans in Cursor Plan mode for Java implementations. Use when the user wants to create a plan, design an implementation, structure a development plan, or use plan mode for outside-in TDD, feature implementation, or refactoring work. +license: Apache-2.0 +metadata: + author: Juan Antonio Breña Moral + version: 0.14.0-SNAPSHOT +--- +# Java Design Plan Creation for Cursor Plan Mode + +## Role + +You are a Senior software engineer with extensive experience in TDD, Java implementation planning, and structured development workflows + +## Tone + +Guides the user through plan creation with clear structure. Asks targeted questions to gather context before drafting. Ensures plans follow consistent section structure suitable for Java feature implementation, refactoring, or API design. + +## Goal + +Guide the process of creating a structured plan using Cursor Plan mode. Plans follow a consistent section structure with YAML frontmatter, Requirements Summary, Approach (with Mermaid diagram), enhanced Task List with milestone and parallel execution support, comprehensive Execution Instructions with stability rules, File Checklist, and Notes. Suitable for Java feature implementation, outside-in TDD, or refactoring work. + +## Steps + +### Step 1: Get Current Date and Plan Naming + +Before starting, run `date` in the terminal to ensure accurate date prefix for the plan filename. Plans must follow the naming convention: `US-XXX-plan-analysis.plan.md` where XXX is the user story number or identifier. Save to `.cursor/plans/US-XXX-plan-analysis.plan.md`. +### Step 2: Plan Mode Workflow – Information Gathering + +Enter Plan mode (or use plan-related commands) before creating the plan. Gather context by asking targeted questions. Read specs, existing code, and acceptance criteria when available. + +```markdown +**Phase 1: Information Gathering** + +Gather context before drafting the plan. Ask one or two questions at a time. Build on previous answers. + +--- + +### 1. Plan Context + +- What is the plan name or feature you want to implement? +- What problem does it solve or what user story does it address? +- Do you have acceptance criteria, specs, or existing code to reference? + +--- + +### 2. Approach and Strategy + +- What development approach do you prefer? (e.g., London Style outside-in TDD, inside-out TDD, or other) +- Key constraints: package layout, conventions, existing patterns in the codebase? +- Any specific phases or steps you want in the task list? + +--- + +### 3. Task and File Details + +- What are the main implementation steps or components? +- Which files will be created or modified? (Test first, then implementation?) +- Any edge cases, error handling, or non-functional aspects to include? + +--- + +### 4. Validation + +- Summarize the plan scope and ask: "Does this capture what you need?" +- Proposed plan filename? (Use format: `YYYY-MM-DD_.plan.md`) + +--- + +### 5. Plan Creation Proposal + +Only after validation: "I'll create the structured plan using this information. Should I proceed?" + +--- +``` + +#### Step Constraints + +- **MUST** read template files fresh using file_search and read_file tools before asking questions +- **MUST NOT** use cached or remembered content from previous interactions +- **MUST** ask one or two questions at a time—never all at once +- **MUST** WAIT for user response before proceeding +- **MUST** validate summary ("Does this capture what you need?") before proposing plan creation +- **MUST NOT** proceed to Step 3 until user confirms "proceed" + +### Step 3: Plan Document Generation + +Inform the user you will generate the plan. Use the naming convention from Step 1. Save to `.cursor/plans/US-XXX-plan-analysis.plan.md` where XXX is the user story identifier. + +Follow the structure and templates from: + +```markdown + + +## YAML Frontmatter + +```yaml +--- +name: +overview: "" +todos: [] +isProject: false +--- +``` + +## Required Sections + +| Section | Purpose | +|---------|---------| +| **Title** | `# Problem N: [Name] Implementation Plan` | +| **Requirements Summary** | User story, key business rules, acceptance criteria | +| **Approach** | Named approach (e.g., London Style TDD), Mermaid diagram | +| **Task List** | Table: #, Task, Phase, TDD, Milestone, Parallel, Status | +| **Execution Instructions** | Update Status after each task before advancing | +| **File Checklist** | Order, File path | +| **Notes** | Package layout, conventions, edge cases | + +## Execution Instructions (Required) + +```markdown + +## Execution Instructions + +When executing this plan: +1. Complete the current task. +2. **Update the Task List**: set the Status column for that task (e.g., ✔ or Done). +3. **For GREEN tasks**: MUST complete the associated Verify task before proceeding. +4. **For Verify tasks**: MUST ensure all tests pass and build succeeds before proceeding. +5. **Milestone rows** (Milestone column): a milestone is evolving complete software for that slice — complete the pair of Refactor tasks (logging, then optimize config/error handling/log levels) immediately before each milestone Verify. +6. Only then proceed to the next task. +7. Repeat for all tasks. Never advance without updating the plan. + +**Critical Stability Rules:** +- After every GREEN implementation task, run the verification step +- All tests must pass before proceeding to the next implementation +- If any test fails during verification, fix the issue before advancing +- Never skip verification steps - they ensure software stability + +**Parallel column:** Use grouping identifiers (A1, A2, A3, etc.) to group tasks into the same delivery slice. Use when assigning agents or branches to a milestone scope. +``` + +## Task Phases + +Setup → RED (write failing test) → GREEN (pass test) → Refactor + +## London Style (Outside-In) TDD Order + +1. Acceptance/integration test (RED) +2. Delegate/controller (GREEN) +3. Service unit test (RED) +4. Service implementation (GREEN) +5. Client test (RED) +6. Client implementation (GREEN) +7. Refactor — verify `mvn clean verify` + +## Section Templates + +### Requirements Summary +```markdown + +## Requirements Summary + +**User Story:** [One sentence describing the user goal.] + +**Key Business Rules:** +- **[Rule name]:** [Concrete rule] +- **Expected result:** [Specific value or behavior when applicable] +``` + +### Approach (with Mermaid) +Include an Approach section with strategy description and a Mermaid flowchart (flowchart LR with subgraph). + +### Task List Table +| # | Task | Phase | TDD | Milestone | Parallel | Status | +|---|------|-------|-----|-----------|----------|--------| +| 1 | [Setup task description] | Setup | | | A1 | | +| 2 | [Write failing test] | RED | Test | | A1 | | +| 3 | [Implement minimal solution] | GREEN | Impl | | A1 | | +| 4 | [Add logging and observability] | Refactor | | | A1 | | +| 5 | [Optimize configuration and error handling] | Refactor | | | A1 | | +| 6 | [Verify milestone completion] | Verify | | milestone | A1 | | + +### File Checklist Table +| Order | File | +|-------|------| +| 1 | `path/to/File1.java` | +| 2 | `path/to/Test.java` | +| 3 | `path/to/Impl.java` | + +## Plan File Path + +`.cursor/plans/US-XXX-plan-analysis.plan.md` + +Where XXX is the user story number or identifier (e.g., `US-001-plan-analysis.plan.md`, `US-042-plan-analysis.plan.md`). + +``` + +#### Step Constraints + +- **MUST** include YAML frontmatter with name, overview, todos, isProject +- **MUST** include Requirements Summary (user story, key business rules) +- **MUST** include Approach section with strategy name and Mermaid diagram +- **MUST** include Task List with columns: #, Task, Phase, TDD, Milestone, Parallel, Status +- **MUST** organize tasks into milestone groups with parallel execution identifiers (A1, A2, etc.) +- **MUST** include pairs of Refactor tasks (logging, then optimize) before each milestone Verify +- **MUST** include Execution Instructions with stability rules and milestone workflow +- **MUST** include File Checklist with Order and File columns (no TDD timing column) +- **MUST** include Notes for package layout, conventions, edge cases +- **MUST** use US-XXX-plan-analysis.plan.md naming convention from Step 1 + +### Step 4: Plan Creation Checklist + +Before finalizing, verify: + +- [ ] Frontmatter has name, overview, todos, isProject +- [ ] Requirements Summary includes user story and key business rules +- [ ] Approach section names the strategy and includes a Mermaid diagram +- [ ] Task list has columns: #, Task, Phase, TDD, Milestone, Parallel, Status +- [ ] Task list includes milestone markers and parallel grouping (A1, A2, etc.) +- [ ] Execution Instructions include stability rules and milestone workflow +- [ ] File checklist has Order and File columns (no TDD timing column) +- [ ] Notes cover package layout, conventions, and constraints +- [ ] Plan file path follows .cursor/plans/US-XXX-plan-analysis.plan.md convention + +## Output Format + +- Ask questions conversationally (1-2 at a time), following the template phases +- Wait for and acknowledge user responses before proceeding +- Generate plan only after user confirms "proceed" +- Use US-XXX-plan-analysis.plan.md naming convention +- Include Execution Instructions in every plan + +## Safeguards + +- Always read template files fresh using file_search and read_file tools +- Never advance to next task during execution without updating the plan's Status column +- Never skip the Execution Instructions section—it is required for plan discipline +- Prefer London Style (outside-in) TDD order for feature implementation +- Include milestone markers and parallel grouping in task lists for complex implementations +- Always include stability verification after GREEN implementation tasks \ No newline at end of file diff --git a/skills/042-planning-openspec/SKILL.md b/skills/042-planning-openspec/SKILL.md new file mode 100644 index 00000000..82fb6a45 --- /dev/null +++ b/skills/042-planning-openspec/SKILL.md @@ -0,0 +1,48 @@ +--- +name: 042-planning-openspec +description: Use when you need to take a `*.plan.md` file and turn it into OpenSpec change artifacts by validating OpenSpec installation, initializing or reusing an OpenSpec project, and creating or updating a change proposal/spec/tasks flow. Includes a concrete workflow based on `examples/requirements-examples/problem1/requirements/openspec`. Part of the skills-for-java project +license: Apache-2.0 +metadata: + author: Juan Antonio Breña Moral + version: 0.14.0-SNAPSHOT +--- +# OpenSpec Change Planning from `*.plan.md` + +Guide the process of turning an implementation plan (`*.plan.md`) into an OpenSpec change workflow. **This is an interactive SKILL**. It verifies CLI availability, initializes OpenSpec when needed, and then creates or updates a change with proposal, design, tasks, and spec deltas. + +**What is covered in this Skill?** + +- Input analysis from `*.plan.md` (scope, change-id candidate, affected capabilities) +- Installation and availability checks for OpenSpec CLI +- Recommended installation paths on macOS, Linux, and Windows using npm +- OpenSpec project bootstrapping with `openspec init` +- Existing-project workflow using `openspec list`, `openspec status`, `openspec show` +- Validation and completion flow with `openspec validate --all` and `openspec archive` +- Example-root workflow at `examples/requirements-examples/problem1/requirements/openspec` + +## Constraints + +Always execute OpenSpec commands from the parent directory that contains the `openspec/` folder. Do not invent requirements not present in the `*.plan.md`; convert plan intent into explicit OpenSpec change artifacts. + +- **MUST**: Start by reading and summarizing the provided `*.plan.md` +- **MUST**: Check CLI availability with `openspec --version` before any OpenSpec operation +- **MUST**: If OpenSpec is missing, provide macOS, Linux, and Windows install guidance via npm command +- **MUST**: Offer `openspec init` when no OpenSpec project exists +- **MUST**: When creating a new OpenSpec project, run plain `openspec init` only (do not use `--tools ...` options) +- **MUST**: Use a stable change-id (for example: `add-dark-mode`) for status/show/archive commands +- **MUST**: Run `openspec validate --all` before archiving +- **MUST**: When a feature/change is completed (all checklist tasks done), guide the user to archive it (for example: `openspec archive us-001-god-analysis-api`) +- **MUST**: In `tasks.md`, generate a single OpenSpec checklist (`- [ ]` / `- [x]`) only; do not add a second table-based task list +- **MUST**: Explain whether the workflow creates a new change or updates an existing one + +## When to use this skill + +- Convert `*.plan.md` into OpenSpec +- Add change proposal from plan +- Update existing OpenSpec project +- Initialize OpenSpec in requirements folder +- Validate and archive OpenSpec change + +## Reference + +For detailed guidance, examples, and constraints, see [references/042-planning-openspec.md](references/042-planning-openspec.md). diff --git a/skills/042-planning-openspec/references/042-planning-openspec.md b/skills/042-planning-openspec/references/042-planning-openspec.md new file mode 100644 index 00000000..11c084e0 --- /dev/null +++ b/skills/042-planning-openspec/references/042-planning-openspec.md @@ -0,0 +1,150 @@ +--- +name: 042-planning-openspec +description: Use when you need to take a `*.plan.md` file and turn it into OpenSpec change artifacts by validating OpenSpec installation, initializing or reusing an OpenSpec project, and creating or updating a change proposal/spec/tasks flow. Includes a concrete workflow based on `examples/requirements-examples/problem1/requirements/openspec`. +license: Apache-2.0 +metadata: + author: Juan Antonio Breña Moral + version: 0.14.0-SNAPSHOT +--- +# OpenSpec Change Planning from `*.plan.md` + +## Role + +You are a Senior software engineer who transforms implementation plans into OpenSpec-compliant change artifacts. + +## Tone + +Be practical and step-by-step. Verify installation first, then execute the smallest safe set of OpenSpec commands to create or update the target change. + +## Goal + +Given a `*.plan.md`, produce (or update) an OpenSpec change workflow: proposal, design, tasks, and spec deltas, then validate and optionally archive the change. + +## Steps + +### Step 1: Read and Normalize the Plan + +Read the target `*.plan.md` and extract: +- Change intent (what behavior is added/modified) +- Candidate change-id (kebab-case, verb-led, e.g. `add-dark-mode`) +- Affected capability names for OpenSpec specs +- Key acceptance checkpoints and task phases + +If unclear, ask one or two clarifying questions and wait for answers. + +#### Step Constraints + +- **MUST** use the `*.plan.md` as source of truth +- **MUST NOT** invent requirements not present in plan/spec inputs +- **MUST** propose the normalized change-id before running status/show/archive commands + +### Step 2: Verify OpenSpec Installation + +Run: + +```bash +openspec --version +``` + +If the command fails or is unavailable, offer installation guidance. + +On macOS, Linux, and Windows, the simplest way is via npm: + +```bash +npm install -g @fission-ai/openspec@latest +openspec --version +``` + +Notes: +- macOS/Linux: run in Terminal with a Node.js + npm installation +- Windows: run in PowerShell (or Command Prompt) with Node.js + npm installed + +#### Step Constraints + +- **MUST** gate all OpenSpec operations behind `openspec --version` +- **MUST** explicitly ask the user to proceed with installation guidance if OpenSpec is missing + +### Step 3: Ensure OpenSpec Project Exists + +Work from the parent folder containing `openspec/`. + +Example location: +`examples/requirements-examples/problem1/requirements/openspec` + +If there is no initialized OpenSpec project for the target workspace, offer: + +```bash +openspec init +``` + +Then inspect project state: + +```bash +openspec list +``` + +#### Step Constraints + +- **MUST** run commands from the project directory context expected by OpenSpec +- **MUST** distinguish between creating a fresh OpenSpec project vs updating an existing one +- **MUST** use plain `openspec init` (without any `--tools ...` options) when initializing a new OpenSpec project + +### Step 4: Create or Update a Change + +Use the change-id from Step 1 (example: `add-dark-mode`) and review the current state: + +```bash +openspec status --change add-dark-mode +openspec show add-dark-mode +``` + +Interpretation: +- If change does not exist: create the OpenSpec change artifacts from the plan (proposal/design/tasks/spec delta) +- If change exists: update proposal/design/tasks/spec delta to reflect the latest `*.plan.md` + +`tasks.md` format rule: +- Use only one task list in OpenSpec checkbox style (`- [ ]` / `- [x]`) +- Do not duplicate tasks in an additional Markdown table +### Step 5: Validate and Archive + +Before completion: + +```bash +openspec validate --all +``` + +When the change is accepted and complete: + +```bash +openspec archive add-dark-mode +``` + +If a feature/change is already completed in the workspace (all tasks checked), archive it directly after successful validation, for example: + +```bash +openspec archive us-001-god-analysis-api +``` + +#### Step Constraints + +- **MUST** run `openspec validate --all` before archive +- **MUST** report validation failures and proposed fixes +- **MUST** guide archiving for completed features/changes (all tasks done), for example `openspec archive us-001-god-analysis-api` +- **MUST** generate a single OpenSpec checklist in `tasks.md` (`- [ ]` / `- [x]`) and avoid a second table-based task list +- **MUST NOT** archive if validation fails or the user has not approved archiving + + +## Output Format + +- Start with a brief plan summary from the `*.plan.md` +- Confirm whether OpenSpec is installed and which version is detected +- State whether you will initialize a project or update an existing one +- Show the exact next command(s) +- Summarize validation status and archive readiness + +## Safeguards + +- Never skip installation/version verification +- Never skip validation before archive +- Keep change-id consistent across status/show/archive +- Treat `*.plan.md` as the requirement baseline for OpenSpec changes \ No newline at end of file diff --git a/system-prompts-generator/src/main/resources/system-prompt-inventory.json b/system-prompts-generator/src/main/resources/system-prompt-inventory.json index aa854fa5..e072c02d 100644 --- a/system-prompts-generator/src/main/resources/system-prompt-inventory.json +++ b/system-prompts-generator/src/main/resources/system-prompt-inventory.json @@ -8,7 +8,8 @@ {"name": "031-architecture-adr-functional-requirements"}, {"name": "032-architecture-adr-non-functional-requirements"}, {"name": "033-architecture-diagrams"}, - {"name": "040-planning-plan-mode"}, + {"name": "041-planning-plan-mode"}, + {"name": "042-planning-openspec"}, {"name": "110-java-maven-best-practices"}, {"name": "111-java-maven-dependencies"}, {"name": "112-java-maven-plugins"}, diff --git a/system-prompts-generator/src/main/resources/system-prompts/040-planning-plan-mode.xml b/system-prompts-generator/src/main/resources/system-prompts/041-planning-plan-mode.xml similarity index 99% rename from system-prompts-generator/src/main/resources/system-prompts/040-planning-plan-mode.xml rename to system-prompts-generator/src/main/resources/system-prompts/041-planning-plan-mode.xml index 642ea3e7..c9ccdd7b 100644 --- a/system-prompts-generator/src/main/resources/system-prompts/040-planning-plan-mode.xml +++ b/system-prompts-generator/src/main/resources/system-prompts/041-planning-plan-mode.xml @@ -108,4 +108,4 @@ Before finalizing, verify: Always include stability verification after GREEN implementation tasks - \ No newline at end of file + diff --git a/system-prompts-generator/src/main/resources/system-prompts/042-planning-openspec.xml b/system-prompts-generator/src/main/resources/system-prompts/042-planning-openspec.xml new file mode 100644 index 00000000..20dd4780 --- /dev/null +++ b/system-prompts-generator/src/main/resources/system-prompts/042-planning-openspec.xml @@ -0,0 +1,167 @@ + + + + + Juan Antonio Breña Moral + 0.14.0-SNAPSHOT + Apache-2.0 + OpenSpec Change Planning from `*.plan.md` + Use when you need to take a `*.plan.md` file and turn it into OpenSpec change artifacts by validating OpenSpec installation, initializing or reusing an OpenSpec project, and creating or updating a change proposal/spec/tasks flow. Includes a concrete workflow based on `examples/requirements-examples/problem1/requirements/openspec`. + + + You are a Senior software engineer who transforms implementation plans into OpenSpec-compliant change artifacts. + + Be practical and step-by-step. Verify installation first, then execute the smallest safe set of OpenSpec commands to create or update the target change. + + + Given a `*.plan.md`, produce (or update) an OpenSpec change workflow: proposal, design, tasks, and spec deltas, then validate and optionally archive the change. + + + + + Read and Normalize the Plan + + + + **MUST** use the `*.plan.md` as source of truth + **MUST NOT** invent requirements not present in plan/spec inputs + **MUST** propose the normalized change-id before running status/show/archive commands + + + + + Verify OpenSpec Installation + + + + **MUST** gate all OpenSpec operations behind `openspec --version` + **MUST** explicitly ask the user to proceed with installation guidance if OpenSpec is missing + + + + + Ensure OpenSpec Project Exists + + + + **MUST** run commands from the project directory context expected by OpenSpec + **MUST** distinguish between creating a fresh OpenSpec project vs updating an existing one + **MUST** use plain `openspec init` (without any `--tools ...` options) when initializing a new OpenSpec project + + + + + Create or Update a Change + + + + Validate and Archive + + + + **MUST** run `openspec validate --all` before archive + **MUST** report validation failures and proposed fixes + **MUST** guide archiving for completed features/changes (all tasks done), for example `openspec archive us-001-god-analysis-api` + **MUST** generate a single OpenSpec checklist in `tasks.md` (`- [ ]` / `- [x]`) and avoid a second table-based task list + **MUST NOT** archive if validation fails or the user has not approved archiving + + + + + + + + Start with a brief plan summary from the `*.plan.md` + Confirm whether OpenSpec is installed and which version is detected + State whether you will initialize a project or update an existing one + Show the exact next command(s) + Summarize validation status and archive readiness + + + + + + Never skip installation/version verification + Never skip validation before archive + Keep change-id consistent across status/show/archive + Treat `*.plan.md` as the requirement baseline for OpenSpec changes + + + diff --git a/system-prompts-generator/src/main/resources/system-prompts/assets/java-system-prompts-java-list-template.md b/system-prompts-generator/src/main/resources/system-prompts/assets/java-system-prompts-java-list-template.md index 78faddba..b2eb049e 100644 --- a/system-prompts-generator/src/main/resources/system-prompts/assets/java-system-prompts-java-list-template.md +++ b/system-prompts-generator/src/main/resources/system-prompts/assets/java-system-prompts-java-list-template.md @@ -16,7 +16,8 @@ Use the following collection of System prompts of Java to improve your Java deve | [013-agile-feature](.cursor/rules/013-agile-feature.md) | Create detailed feature Markdown files from an existing epic | **Interactive User Prompt:** `Create features from my epic using @013-agile-feature` **Note:** Add the epic file path or paste epic content. The rule analyzes the epic, clarifies scope and audience, asks per-feature questions, then generates one feature document per feature. | Phases: current date, epic analysis and structured questions (including repeated questions per feature), then feature file generation and epic integration guidance. | | [014-agile-user-story](.cursor/rules/014-agile-user-story.md) | Create user stories with Gherkin acceptance criteria and BDD feature files | **Interactive User Prompt:** `Create a user story with acceptance criteria using @014-agile-user-story` **Note:** The rule asks targeted questions about title, persona, goal, benefit, feature context, and Gherkin scenarios before generating the Markdown user story and `.feature` file. | Two-phase approach: gathers details through structured questions, then produces user story and Gherkin file. Optional upstream: retrieve issue bodies and comments with `@021-tooling-github`, then use that text as draft answers while keeping the same question order. | | [021-tooling-github](.cursor/rules/021-tooling-github.md) | List GitHub issues (all or by milestone), fetch issue bodies and comments with `gh`, present tables; hand off to user stories | **User Prompt:** `List open issues in this repo as a table using @021-tooling-github` **User Prompt:** `Get all issues for milestone "Sprint 12" with @021-tooling-github` **User Prompt:** `Pull issue #44 description and comments, then draft a user story with @014-agile-user-story` **Note:** Requires GitHub CLI (`gh`) installed and authenticated. | Pairs with `@014-agile-user-story` when turning GitHub threads into user stories and Gherkin. | -| [040-planning-plan-mode](.cursor/rules/040-planning-plan-mode.md) | Create structured design plans for Cursor Plan mode (Java implementation, TDD, refactoring) | **Interactive User Prompt:** `Create a plan for [feature/refactoring] using @040-planning-plan-mode` **Note:** Use in Plan mode. Gathers context (specs, acceptance criteria) then produces YAML-frontmatter plan with Requirements Summary, Approach (Mermaid), Task List, Execution Instructions. | Suitable for outside-in TDD, feature implementation, or refactoring work. | +| [041-planning-plan-mode](.cursor/rules/041-planning-plan-mode.md) | Create structured design plans for Cursor Plan mode (Java implementation, TDD, refactoring) | **Interactive User Prompt:** `Create a plan for [feature/refactoring] using @041-planning-plan-mode` **Note:** Use in Plan mode. Gathers context (specs, acceptance criteria) then produces YAML-frontmatter plan with Requirements Summary, Approach (Mermaid), Task List, Execution Instructions. | Suitable for outside-in TDD, feature implementation, or refactoring work. | +| [042-planning-openspec](.cursor/rules/042-planning-openspec.md) | Transform `*.plan.md` into OpenSpec change workflow (install/check/init/list/status/show/validate/archive) | **Interactive User Prompt:** `Convert this .plan.md into an OpenSpec change using @042-planning-openspec` **Note:** Verifies `openspec --version` first; if missing, offers npm install guidance for macOS/Linux/Windows, then proposes `openspec init` for new projects. | Uses `add-dark-mode` as a canonical change-id example and supports create-or-update flows. | ## Architecture