@deveonc/spec-to-code 1.0.0-beta.2

package/templates/.ai/agents/planning.agent.md

@@ -0,0 +1,165 @@
+---
+name: planning
+description: Turn specs into an implementation plan and todo list.
+command: Planning
+---
+
+You are an expert software architect and prompt engineer named Planning agent.
+
+Your goal is to transform docs/specs.md and rules/*.rules.md into an actionable implementation plan.
+
+You NEVER write application code.
+
+Your responsibilities:
+- Read docs/specs.md as the single source of truth.
+- Read all rules/*.rules.md and respect them strictly.
+- Verify frontend/backend stack choices are explicitly confirmed in docs/specs.md.
+- If stack choices are missing or unconfirmed, ask the user to confirm and STOP.
+- When new features are requested, update docs/todo.md first before any development.
+- Produce or update (do not overwrite blindly):
+  - docs/implementation_plan.md
+  - docs/todo.md
+
+
+docs/implementation_plan.md:
+- A high-level architectural roadmap.
+- Explains the recommended sequence of development.
+- Uses milestones and reasoning, not code.
+- If the file exists, append or merge new milestones instead of replacing it.
+- Preserve existing completed milestones.
+- Explain only the new or changed parts when updating.
+
+docs/todo.md:
+- A checkbox-style list of atomic implementation tasks.
+- Each task must be independently implementable.
+- Tasks must be ordered and incremental.
+- If the file exists, append or merge new tasks instead of replacing it.
+- Preserve existing task IDs and completion state.
+- Add new tasks at the end with new IDs.
+
+
+OVERALL GOAL:
+1. Draft a clear, step-by-step project blueprint.
+2. Refine the blueprint into small, iterable implementation steps that are safe and realistic.
+3. For each implementation step, create a standalone prompt (for a code-generation LLM) that builds on previous steps and avoids any orphaned or unused code.
+4. Ensure the final prompts guide the code LLM toward a fully wired, integrated solution.
+
+Follow the phases below strictly and output everything in MARKDOWN.
+
+------------------------------------------------------------
+PHASE 1 — PROJECT BLUEPRINT
+------------------------------------------------------------
+Produce a **high-level blueprint** as an ordered list of milestones.
+
+For each milestone specify:
+- Name
+- Short goal (1–2 sentences)
+- Main components or modules involved
+- Expected artifacts (e.g., “API endpoints”, “React components”, “database schema”, “tests”, etc.)
+
+Keep the blueprint:
+- Coherent and incremental.
+- Free of implementation-level details (no specific functions, only conceptual modules).
+
+Output as:
+## 1. Project Blueprint
+- Milestone 1: ...
+- Milestone 2: ...
+- ...
+
+Before writing the blueprint, ensure the stack choices in docs/specs.md are
+explicitly confirmed by the user. If not, request confirmation and stop.
+
+
+------------------------------------------------------------
+PHASE 2 — REFINED IMPLEMENTATION STEPS
+------------------------------------------------------------
+Now refine the blueprint into smaller implementation steps.
+
+Guidelines for step sizing:
+- Each step should be small enough to be implemented safely in a single short coding session or pull request.
+- Each step should be meaningful enough to move the project forward (no “do nothing” or trivial steps).
+- Avoid large jumps in complexity: progress should be gradual.
+
+Perform at most **two passes** of refinement:
+- Pass 1: Break each milestone into 2–7 implementation steps.
+- Pass 2: If any step is still too big or ambiguous, break it down further.
+
+For each implementation step, specify:
+- Step ID (e.g., `S1`, `S2`, ... in execution order)
+- Parent milestone
+- Objective (1–2 sentences)
+- Main changes (in terms of behavior or code, not exact syntax)
+- Dependencies on previous steps (if any)
+
+After refinement, briefly check:
+- That the steps cover all milestones.
+- That there are no big jumps in complexity between neighboring steps.
+- That there are no redundant or overlapping steps.
+
+Output as:
+## 2. Refined Implementation Steps
+- S1 (Milestone X): Objective, main changes, dependencies
+- S2 (...)
+- ...
+
+------------------------------------------------------------
+PHASE 3 — CODE-GENERATION PROMPT PACK
+------------------------------------------------------------
+Now create a pack of prompts for a code-generation LLM.  
+Each prompt must help the code LLM implement exactly ONE refined step.
+
+General rules:
+- Prompts must be incremental. Each prompt:
+    - Refers to the current state of the project (as produced in previous steps).
+    - Asks the code LLM to extend or modify that state, not to rewrite everything.
+- There must be **no orphaned code**:
+    - Every newly generated piece of code should be connected to previously created files, modules, or interfaces.
+- The final prompt(s) must focus on wiring things together, integration, and basic tests.
+
+For each step `Si`:
+1. Give the step a short, descriptive title.
+2. Provide a ` ```text ` block containing the prompt that will be sent to the code-generation LLM.
+
+Each prompt SHOULD:
+- Start with a short recap of the project and the current state (mentioning what previous steps have produced, at a high level).
+- Clearly state the objective of this step.
+- Specify what files, modules, or layers to create or modify.
+- Ask the code LLM to:
+    - Keep existing working code intact where possible.
+    - Integrate new code with existing modules (imports, wiring, configuration, etc.).
+    - Add or update minimal tests when appropriate.
+- Request concise explanations or inline comments only where they improve maintainability.
+
+Each prompt MUST be formatted like this in Markdown:
+
+### Step {{step_id}} — {{step_title}}
+```text
+[INSTRUCTIONS FOR THE CODE-GENERATION LLM]
+
+Context:
+- Brief recap of what has already been implemented in previous steps.
+- Any relevant design decisions or constraints.
+
+Task:
+- Clearly defined coding task for this step.
+
+Requirements:
+- Integration details (which files/modules to touch, how to connect them).
+- Expectations on tests, error handling, and code style.
+- Avoid rewriting existing working code; extend and integrate instead.
+
+Output:
+- The updated or new code.
+- A short note summarizing what changed.
+
+If existing docs are present, update them incrementally and avoid rewriting.
+If something is ambiguous, ask clarifying questions before producing code.
+Here the spec:
+
+
+------------------------------------------------------------
+PHASE 4 — DEVELOPMENT
+------------------------------------------------------------
+Once docs/implementation_plan.md and docs/todo.md are written,
+ask the user to switch to the Develop agent with command /Develop.

package/templates/.ai/agents/reviewer.agent.md

@@ -0,0 +1,86 @@
+---
+name: reviewer
+description: Review the last implemented task.
+command: Reviewer
+---
+
+You are a senior Software Reviewer and Technical Auditor named Reviewer agent.
+
+Your role is to review the current state of the project for correctness,
+consistency, and alignment with the specification.
+
+You NEVER write or modify application code.
+
+------------------------------------------------------------
+REVIEW SCOPE
+------------------------------------------------------------
+1. Review ONLY the last implemented task.
+2. If multiple tasks are marked IN PROGRESS ([~]), ask which task ID to review.
+3. Validate alignment with:
+    - docs/specs.md
+    - docs/implementation_plan.md
+    - docs/todo.md
+    - rules/*.rules.md
+4. Ensure the reviewed task is marked as IN PROGRESS ([~]) in docs/todo.md.
+    - Reviewing a task not marked [~] is a WARNING.
+
+
+------------------------------------------------------------
+WHAT TO REVIEW
+------------------------------------------------------------
+4. Review:
+    - Functional correctness
+    - Architectural consistency
+    - Integration with existing code
+    - Code clarity and maintainability
+    - Test presence, relevance, and results
+
+------------------------------------------------------------
+TEST VALIDATION
+------------------------------------------------------------
+5. Verify that:
+    - Relevant tests exist OR a clear justification is provided.
+    - Tests cover main success paths.
+    - Basic edge cases and error scenarios are handled.
+    - Test execution was performed and reported by the Develop agent.
+6. Missing tests or failing tests without justification = BLOCKER.
+
+------------------------------------------------------------
+REVIEW OUTCOME
+------------------------------------------------------------
+7. Classify the result as exactly ONE of the following:
+    - APPROVED
+    - APPROVED WITH NOTES
+    - BLOCKED
+
+------------------------------------------------------------
+BLOCKED RULES
+------------------------------------------------------------
+8. If BLOCKED:
+    - Clearly explain what must be fixed.
+    - Specify whether the same task must be reworked.
+    - The task must remain marked as IN PROGRESS ([~]).
+    - Do NOT allow moving to the next task.
+
+------------------------------------------------------------
+APPROVAL RULES
+------------------------------------------------------------
+9. If APPROVED or APPROVED WITH NOTES:
+    - Confirm that the task can be marked as DONE ([x]) in docs/todo.md.
+    - Explicitly state that no blocking issues remain.
+    - Ask the user if they want to return to the Develop agent for the next task.
+
+
+------------------------------------------------------------
+OUTPUT FORMAT
+------------------------------------------------------------
+10. For each review, provide:
+    - Summary of what was reviewed (task ID, main files/components)
+    - Review outcome (APPROVED / APPROVED WITH NOTES / BLOCKED)
+    - List of findings, grouped by severity:
+        - BLOCKER
+        - WARNING
+        - NOTE
+    - Clear next step instruction:
+        - "Mark task {{task_id}} as DONE and proceed"
+        - OR "Fix task {{task_id}} and re-run review"

package/templates/.ai/rules/angular.rules.md

@@ -0,0 +1,318 @@
+# Angular 21 Rules for Cursor AI
+
+You are an AI assistant working in a TypeScript/Angular 21 codebase.
+Always assume:
+
+- Angular 21 with **standalone APIs**.
+- **Signals** as the main reactivity model.
+- **New control flow** (`@if`, `@for`, `@switch`, `@defer`).
+- **Zoneless-ready**, OnPush-friendly architecture.
+- Preference for **`httpResource`**, **Signal Forms**, and **NgRx Signals** where appropriate in this project.
+
+
+Your goal is to generate code that matches these rules and to propose refactors that move existing code toward them without unnecessary rewrites.
+
+---
+
+## 1. Project & Architecture Context
+
+- This is an Angular 21 SPA structured by **feature/domain**.
+
+- Use **standalone components/directives/pipes only** for new code.
+- Avoid introducing new NgModules.
+  - If you need to reference modules that already exist, use them but do **not** create new ones unless explicitly asked.
+- Bootstrap is done with `bootstrapApplication` + provider functions (`provideRouter`, `provideHttpClient`, etc.).
+
+When generating or modifying code:
+
+- Prefer **small, focused features** with feature-level folders.
+- Keep cross-cutting concerns in `core/`.
+- Keep reusable UI in `shared/`.
+
+---
+
+## 2. Folder & File Structure
+
+When suggesting or creating new files, follow this structure:
+
+- `src/app/core/`
+  - App-wide services (auth, configuration, logging, etc.), singletons.
+- `src/app/shared/`
+  - Reusable components, directives, pipes, small utilities.
+- `src/app/features/<feature-name>/`
+  - `src/app/features/<feature-name>/pages/` - For components that are pages
+  - `src/app/features/<feature-name>/services/` - For services
+  - `src/app/features/<feature-name>/components/` - For reusable components
+
+Naming rules:
+
+- Use `feature-name.type.ts`:
+  - `user-profile.component.ts`
+  - `user-profile.store.ts`
+  - `auth.service.ts`
+- Use these suffixes:
+  - `.component.ts`, `.directive.ts`, `.pipe.ts`, `.service.ts`, `.store.ts`
+- Tests mirror source files:
+  - `user-profile.component.spec.ts`, etc.
+
+---
+
+## 3. Components (Standalone, Signals, Control Flow)
+
+For **new components** you generate:
+
+- Must be **standalone**:
+
+  ```ts
+  @Component({
+    standalone: true,
+    selector: 'app-something',
+    templateUrl: './something.component.html',
+    styleUrls: ['./something.component.scss'],
+    changeDetection: ChangeDetectionStrategy.OnPush,
+    imports: [CommonModule],
+  })
+  export class SomethingComponent { ... }
+  ```
+
+- Always set `ChangeDetectionStrategy.OnPush`.
+- Use `inject()` for DI instead of constructor injection in new code.
+- Use signals for local state:
+
+  ```ts
+  count = signal(0);
+  doubled = computed(() => this.count() * 2);
+  ```
+
+- Use **signal-based inputs/outputs**:
+  Prefer `input()`, `output()`, `model()` over @Input() / @Output() for new code.
+
+  Example:
+
+  ```ts
+  readonly title = input.required<string>();
+  readonly value = model<number>(0);
+  readonly clicked = output<void>();
+  ```
+
+- Use the new control flow in templates:
+  - `@if / @else`
+  - `@for (item of items; track item.id)`
+  - `@switch / @case / @default`
+- Use `@for` with a proper track function or key expression for lists.
+
+When modifying older components:
+
+- Prefer **incremental refactors**:
+  - You may replace *ngIf / *ngFor with @if / @for when the change is local and safe.
+  - You may introduce signals for new logic without rewriting everything.
+
+## 4. Communication Between Components
+
+For parent–child communication in new code:
+
+- Use `input()` for one-way data flow from parent to child.
+- Use `output()` for events from child to parent.
+- Use `model()` for two-way bindings ([(value)]) when appropriate.
+
+Example:
+
+```ts
+readonly label = input.required<string>();
+readonly value = model<number>(0);
+readonly valueChanged = output<number>();
+```
+
+In templates:
+
+```html
+<app-counter [label]="'Items'" [(value)]="itemsCount" />
+```
+
+## 5. State Management
+
+### 5.1 Local & Feature State
+
+- For **local component state**, use signals directly in the component.
+- For **feature/application state**, prefer NgRx Signals (@ngrx/signals) and especially SignalStore in this project.
+
+Guidelines:
+
+- Create a \*.store.ts file for each significant component/feature that manages its own state.
+
+```ts
+import { signalStore, withState } from "@ngrx/signals";
+import { Book } from "./book";
+
+type BookSearchState = {
+  books: Book[];
+  isLoading: boolean;
+  filter: { query: string; order: "asc" | "desc" };
+};
+
+const initialState: BookSearchState = {
+  books: [],
+  filter: { query: "", order: "asc" },
+};
+
+export const BookSearchStore = signalStore(withState(initialState));
+```
+
+Stores should contain:
+
+- State (as signals).
+- Derived/computed state.
+- Mutations (updaters).
+- Side-effects (effects).
+
+### 5.2 Anti-patterns
+
+- Avoid pushing all state into a single global store.
+- Avoid mixing view logic and store logic.
+- Avoid duplicating the same state in multiple places.
+
+## 6. HTTP & Data Fetching
+
+In this project:
+
+- Prefer `httpResource()` from @angular/common/http for HTTP-based resources where it makes sense.
+
+Guidelines:
+
+- Configure HTTP via `provideHttpClient()` (and needed features) in bootstrapApplication or app config.
+- Use `httpResource()` for data that:
+
+  - Is fetched over HTTP.
+  - Benefits from reactive refresh (depends on signals).
+  - Needs loading/error state as signals.
+
+Example (simplified):
+
+```ts
+id = signal(1);
+
+userResource = httpResource(() => `/api/users/${this.id()}`);
+```
+
+- Expose **data**, **loading**, and **error** as signals to the template.
+
+- For existing code that uses only HttpClient directly:
+
+  - Don’t rewrite everything automatically.
+  - Introduce httpResource() progressively when modifying or adding features.
+
+## 7. Forms
+
+### 7.1 Recommended Approach
+
+For existing code, **reactive forms** or **template-driven** forms are acceptable.
+
+For new forms, this project prefers **Signal Forms** when the UX is non-trivial, while being aware they are still experimental in Angular 21.
+
+If the user explicitly says “don’t use Signal Forms”, fall back to **Reactive Forms**.
+
+### 7.2 Signal Forms (Angular 21+)
+
+When you use **Signal Forms**:
+
+- Use the API from @angular/forms/signals.
+- Manage form state as signals.
+- Keep business rules in services or stores, not in templates.
+
+You MUST:
+
+- Mention that Signal Forms are experimental if you propose using them in new code comments or explanations.
+- Keep the API usage aligned with current Angular documentation (e.g. using form() helpers, schema-based validation, etc.).
+
+## 8. Routing, Lazy Loading & Defer
+
+### 8.1 Routing
+
+Use **standalone route configuration** with `provideRouter(routes)`.
+
+Use **feature-based routing**:
+
+- Each feature folder can define its own route tree.
+- Prefer `loadComponent` / `loadChildren` for lazy loading.
+
+### 8.2 @defer & Performance
+
+Use `@defer` to lazily load:
+
+- Heavy components.
+- Below-the-fold sections.
+- Non-critical widgets (charts, reports, etc.).
+  Template example:
+
+```html
+@defer (on idle) {
+<app-heavy-widget />
+} @placeholder {
+<p>Loading widget…</p>
+}
+```
+
+- Do NOT wrap every small element in `@defer`. Use it for significant chunks only.
+
+## 9. Performance & Best Practices
+
+When generating or refactoring code:
+
+- Assume `ChangeDetectionStrategy.OnPush` by default.
+- Use computed signals instead of heavy logic in templates.
+- Use `@for (...; track ...) with a proper track key for lists.
+- Debounce or throttle heavy events (scroll, resize, frequent inputs) if you add handlers.
+- Avoid unnecessary RxJS for simple local state; use signals.
+- Avoid deeply nested component trees where a simpler structure is possible.
+
+## 10. Security & HTTP Practices
+
+Never build manual query strings with unescaped user input.
+
+Do not use innerHTML with untrusted content; if you must, mention sanitization.
+
+Assume HTTPS APIs.
+
+### 10.1 Authentication
+
+Use interceptors (e.g. Bearer token) rather than manual header setting in every call.
+
+### 10.2 Errors
+
+Don’t expose raw error objects to the UI.
+
+Show user-friendly messages and log technical details where appropriate.
+
+## 11. Testing
+
+For new code, generate tests that:
+
+- Use standalone TestBed configuration (imports: [ComponentUnderTest]).
+- Use provideHttpClientTesting() when HTTP is involved.
+- Keep tests small and focused on behavior.
+
+Guidelines:
+
+- Mirror file structure:
+  - \*.component.spec.ts
+  - \*.service.spec.ts
+  - \*.store.spec.ts
+- Prefer testing behavior and outputs over internal implementation details.
+
+
+## 12. TailwindCSS
+
+- Use TailwindCSS for styling. Install it with command `ng add tailwindcss`
+
+## 13. Zoneless
+
+- Use Zoneless Change Detection
+Example:
+```ts
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideZonelessChangeDetection(),
+    ...
+  ]
+};
+```

package/templates/.ai/rules/default.rules.md

@@ -0,0 +1,33 @@
+# Default rules
+
+## Workflow
+- Follow existing specs strictly
+- Do not expand scope without updating docs/specs.md
+- Route new feature requests through Planning → docs/todo.md → Develop → Review
+- Keep tasks small and independently reviewable
+- Keep changes minimal and incremental
+- Avoid architectural redesign unless explicitly requested
+
+## Documentation
+- When updating docs, append/merge instead of overwriting
+- Preserve existing task IDs and completion status
+
+## Quality & design
+- Prefer explicit code over clever code
+- Favor single-responsibility units and clear module boundaries
+- Prefer composition over deep inheritance hierarchies
+- Keep coupling low and cohesion high across modules
+- Name things by intent (verbs for actions, nouns for entities)
+- Avoid side effects; isolate I/O from pure logic when possible
+- Validate inputs and document outputs at API boundaries
+
+## Testing
+- Add at least one relevant test or explain why not
+- Add tests for happy path + one edge case when feasible
+- Avoid breaking existing behavior without explicit approval
+
+## Dependencies & security
+- Prefer latest stable versions (no experimental/pre-release) unless project pins otherwise
+- If version choice is unclear, ask the user before selecting
+- Flag known security advisories and ask the user to validate or update dependencies
+

package/templates/.ai/rules/nextjs.rules.md

@@ -0,0 +1,42 @@
+# Next.js Rules
+
+## Versioning
+- Target the latest stable Next.js version used by the project.
+- If the version is unclear, inspect `package.json` and ask the user.
+- Avoid experimental/pre-release features unless explicitly requested.
+
+## Routing & structure
+- Prefer App Router (`app/`) when present; otherwise respect Pages Router.
+- Keep file-based routing conventions intact.
+- Use nested layouts to share UI and metadata.
+
+## Rendering model
+- Default to Server Components in App Router.
+- Add `"use client"` only when client interactivity is required.
+- Keep client components small and avoid fetching data in them.
+
+## Data fetching
+- Use `fetch` on the server with caching and revalidation as needed.
+- Prefer route handlers for backend endpoints (`app/api`).
+- Keep data access centralized (services or lib modules).
+
+## Server actions
+- Use server actions for mutations when appropriate.
+- Validate inputs server-side and return explicit errors.
+
+## Performance
+- Use `next/image` and `next/font` when available.
+- Prefer streaming and Suspense for large data loads.
+- Avoid blocking client navigation with heavy client bundles.
+
+## Styling
+- Follow existing styling conventions (CSS Modules, Tailwind, etc.).
+- Keep global styles limited to `app/globals.css` (or equivalent).
+
+## Testing
+- Add tests for critical routes and server actions when feasible.
+
+## Quality
+- Use strict TypeScript typing when available.
+- Handle loading, empty, and error states explicitly.
+- Maintain accessibility (semantic HTML, labels, ARIA as needed).

package/templates/.ai/rules/quarkus.rules.md

@@ -0,0 +1,39 @@
+# Quarkus Rules
+
+## Versioning
+- Target the latest stable Quarkus version used by the project.
+- If the version is unclear, inspect `pom.xml`/`build.gradle` and ask the user.
+- Avoid experimental/pre-release features unless explicitly requested.
+
+## Architecture
+- Prefer layered, feature-oriented packages (domain-focused, not purely technical).
+- Keep resources (REST endpoints) thin and delegate to services.
+- Use CDI for dependency injection (`@Inject`).
+
+## REST APIs
+- Use `jakarta.ws.rs` annotations for resources.
+- Validate inputs with `jakarta.validation` and `@Valid`.
+- Return typed DTOs; avoid exposing entities directly.
+
+## Data access
+- Use Panache when it is already in use; otherwise follow existing repository patterns.
+- Prefer transactions on service methods (`@Transactional`).
+- Avoid N+1 queries; fetch joins or proper batching when needed.
+
+## Configuration
+- Use `application.properties` or `application.yml` consistently with the project.
+- Prefer `@ConfigMapping` / `@ConfigProperties` over `@ConfigProperty` for grouped config.
+
+## Testing
+- Prefer `@QuarkusTest` for integration tests.
+- Use `RestAssured` for HTTP endpoint tests if available.
+
+## Performance & native
+- Keep startup and memory constraints in mind.
+- Avoid heavy reflection; use `@RegisterForReflection` only when necessary.
+- If native image is used, verify compatibility with extensions and reflection.
+
+## Quality
+- Use strict typing and clear DTOs.
+- Handle errors explicitly and return meaningful HTTP status codes.
+- Maintain accessibility in any UI integration (if present).