@rrgarciach/flow-spec 0.1.0

package/template/docs/base-standards.md

@@ -0,0 +1,114 @@
+---
+description: This document contains all development rules and guidelines for this project, applicable to all AI agents (Claude, Cursor, Codex, Gemini, etc.).
+alwaysApply: true
+---
+
+## 1. Core Principles
+
+- **Small tasks, one at a time**: Always work in baby steps, one at a time. Never go forward more than one step.
+- **Test-Driven Development**: Start with failing tests for any new functionality (TDD), according to the task details.
+- **Type Safety**: All code must be fully typed.
+- **Clear Naming**: Use clear, descriptive names for all variables and functions.
+- **Incremental Changes**: Prefer incremental, focused changes over large, complex modifications.
+- **Question Assumptions**: Always question assumptions and inferences.
+- **Pattern Detection**: Detect and highlight repeated code patterns.
+
+## 2. Language Standards
+- **English Only**: All technical artifacts must always use English, including:
+    - Code (variables, functions, classes, comments, error messages, log messages)
+    - Documentation (README, guides, API docs)
+    - Monday.com items (titles, updates, comments)
+    - Data schemas and database names
+    - Configuration files and scripts
+    - Git commit messages
+    - Test names and descriptions
+
+## 3. Specific standards
+
+For detailed standards and guidelines specific to different areas of the project, refer to:
+
+- [Backend Standards](./backend-standards.md) - API development, database patterns, testing, security and backend best practices
+- [Frontend Standards](./frontend-standards.md) - React components, UI/UX guidelines, and frontend architecture
+- [Documentation Standards](./documentation-standards.md) - Technical documentation structure, formatting, and maintenance guidelines, including AI standards like this document
+
+## 4. Project Skills
+
+- Skills live in `ai-specs/skills`.
+- When a request matches a skill, load and follow the corresponding `SKILL.md` automatically before continuing.
+- Also load any referenced files in the skill folder (for example, `references/*.md`) when the skill requires them.
+
+## 5. Symlink Integrity and Multi-Agent Portability
+
+- **Canonical Source**: Keep reusable artifacts in `ai-specs` as the canonical source. Agent-specific paths (such as `.claude` and `.cursor`) should reference them through symlinks when possible.
+- **Update Safety**: Whenever a file is renamed, moved, or its suffix changes, verify and update all symlinks that target it before considering the change complete.
+- **New Artifact Linking**: Whenever creating a new artifact that requires multi-agent exposure (for example new agents or skills in `ai-specs`), create the corresponding symlinks from the expected agent-specific reference paths.
+- **External Customization Review**: Whenever customization is introduced outside `ai-specs`, evaluate whether it should be moved into `ai-specs` and replaced with symlinks from the original locations.
+- **Completion Gate**: A change is incomplete if it leaves broken symlinks, stale targets, or duplicated canonical artifacts across agent-specific folders.
+
+## 6. OpenSpec Tasks Mandatory Steps
+
+When creating or updating OpenSpec `tasks.md` artifacts, follow these requirements.
+
+### 6.1 Read OpenSpec configuration first
+
+- **Required first action**: Read `openspec/config.yaml` before drafting or editing any `tasks.md` file.
+- **Purpose**: Capture mandatory steps, naming conventions, task structure, testing expectations, and documentation requirements from project configuration.
+
+### 6.2 Required backend task structure
+
+For backend changes, ensure the checklist includes these mandatory steps in order:
+
+1. **Step 0 (must be first)**: Create and switch to feature branch:
+   - `feature/[ticket-id]-backend` or `feature/[change-name]-backend`
+2. **Review and update existing unit tests (MANDATORY)**
+3. **Run unit tests and verify database state (MANDATORY)**
+4. **Manual endpoint testing with curl (MANDATORY - AGENT MUST EXECUTE)**
+5. **E2E testing with Playwright MCP when applicable (MANDATORY - AGENT MUST EXECUTE)**
+6. **Update technical documentation (MANDATORY)**
+
+### 6.3 Manual testing execution is agent responsibility
+
+- **Never delegate testing to the user** for steps required by `tasks.md`.
+- The agent must start required services, run tests, validate outcomes, and restore data state after CREATE/UPDATE/DELETE operations.
+- The agent must only mark tasks as completed (`[x]`) after required tests pass and cleanup is complete.
+
+### 6.4 Mandatory curl coverage (for endpoint work)
+
+Execute and verify:
+- GET endpoints
+- POST endpoints (with cleanup)
+- PUT/PATCH endpoints (with revert)
+- DELETE endpoints (with recreation/restore)
+- Error cases (validation, 404, auth as applicable)
+
+Document commands, responses, and restoration actions.
+
+### 6.5 Mandatory Playwright E2E coverage (when applicable)
+
+For frontend workflows or frontend/backend integration changes:
+- Run E2E flows with Playwright MCP tools
+- Validate success and error paths
+- Verify data persistence and consistency
+- Clean test data and restore environment state
+
+### 6.6 Completion checklist before finalizing `tasks.md`
+
+- Step 0 branch creation is first
+- Mandatory steps are present and sequential
+- Mandatory labels are explicit
+- Branch name matches backend convention
+- Manual testing tasks explicitly state "AGENT MUST EXECUTE"
+- Database restoration steps are included for mutating operations
+- E2E step is present when frontend workflow impact exists
+
+### 6.7 Mandatory artifact updates for change requests between `/apply` and `/archive`
+
+If a new fix/change is requested after `/apply` and before `/archive`, treat it as a spec update first (never code-only first).
+
+Required order:
+1. Update affected OpenSpec artifacts (scenarios, requirements/specs, `tasks.md`).
+2. Re-run artifact generation/update step when needed (`/continue`, `/ff`, or equivalent).
+3. Implement code only after artifacts reflect the new request.
+4. Re-run verification against updated artifacts before archiving.
+
+Do not close this window with direct coding that is not reflected in OpenSpec artifacts.

package/template/docs/data-model.md

@@ -0,0 +1,26 @@
+# Data Model Documentation
+
+> This is an empty skeleton. Replace every `_TODO_` below with your project's real domain and database model.
+
+## Model Descriptions
+
+_TODO: for each core entity, describe its purpose, fields (name, type, constraints), and primary key._
+
+Example shape to follow per entity:
+
+```
+### EntityName
+_One-line description of what this entity represents._
+
+**Fields:**
+- `id`: TODO (Primary Key)
+- `field`: TODO (type, constraints)
+```
+
+## Relationships
+
+_TODO: describe how entities relate to each other (1:1, 1:N, N:M) and any cascade/delete rules._
+
+## Entity-Relationship Diagram
+
+_TODO: add an ERD (e.g. as a Mermaid `erDiagram` block) once the model is defined._

package/template/docs/development_guide.md

@@ -0,0 +1,36 @@
+# Development Guide
+
+> This is an empty skeleton. Replace every `_TODO_` below with your project's real setup instructions.
+
+## 🚀 Setup Instructions
+
+### Prerequisites
+
+_TODO: list required runtimes and tools (e.g. Node version, package manager, Docker, cloud CLI)._
+
+### 1. Clone the Repository
+
+```bash
+git clone git@github.com:your-org/your-repo.git
+cd your-repo
+```
+
+### 2. Environment Configuration
+
+_TODO: describe required environment variables/files and where to get their values._
+
+### 3. Dependencies
+
+_TODO: install steps for backend/frontend/infra dependencies._
+
+### 4. Local Services
+
+_TODO: how to start any local services this project depends on (database, queues, mocked cloud services, etc.)._
+
+## 🧪 Running Tests
+
+_TODO: how to run unit, integration, and end-to-end tests locally._
+
+## 🚀 Deployment
+
+_TODO: how this project is deployed (environments, pipeline, IaC tooling)._

package/template/docs/documentation-standards.md

@@ -0,0 +1,49 @@
+---
+description: Standards and best practices for technical documentation in this project, including documentation structure, update processes, and language rules.
+globs:
+alwaysApply: true
+---
+# Rules and Patterns for documentation and AI specs
+
+## Introduction
+Technical documentation applies to all the documentation relative to the project, such as the data model, README, API specs, and other MD docs that describe how the project is structured, runs, and operates.
+AI specs refers to the documents that explain AI agents how to behave, document, plan, code, etc, which includes team agreements, standards and conventions.
+
+## General rules
+- ALWAYS WRITE IN ENGLISH, including comments and any explanation in the files. This applies both to creating new documentation and updating existing one, and it also applies to documentation within the code (comments, explanations of functions or fields, etc.).
+
+
+
+## Technical Documentation
+Before making any commit or git push, or if you're asked to document a commit, you must ALWAYS review which technical documentation should be updated.
+
+When updating documentation, I will:
+1. Review all recent changes in the codebase
+2. Identify which documentation files need updates based on the changes. Some clear examples:
+   - For data model changes: Update data model definition section in data-model.md
+   - For API changes: Update api-spec.yml
+   - For changes in libraries, database migrations, or anything that changes the installation process, update *-standards.md
+3. Update each affected documentation file in English, maintaining consistency with existing documentation
+4. Ensure all documentation is properly formatted and follows the established structure
+5. Verify that all changes are accurately reflected in the documentation
+6. Report which files were updated and what changes were made
+
+## AI specs
+
+This rule establishes a mandatory process for the AI to:
+*   Learn from user feedback, guidance, and suggestions during interactions.
+*   Identify opportunities to improve existing Development Rules based on these learnings proactively.
+*   Keep the AI's assistance aligned with evolving project needs and user expectations.
+*   Incorporate user feedback into the AI's operational framework to maximize its value.
+
+This rule is applicable after any interaction where the user provides explicit or implicit feedback, suggestions, corrections, new information, or expresses preferences. **The AI MUST actively analyze all user interactions for such learning opportunities, not only passively waiting for direct feedback, to proactively refine its understanding and the project's best practices.**
+
+### Common Pitfalls and Anti-Patterns to be avoided by the AI
+
+*   **Skipping Approval Process:** Applying rule modifications without obtaining explicit user review and approval first.
+*   **Unlinked Proposals:** Proposing rule changes without clearly connecting them to the specific user feedback or insights gained from the interaction.
+*   **Imprecise Modifications:** Suggesting modifications without precisely identifying which rule or specific sections within a rule should be changed, hindering effective user review.
+*   **Unaddressed Feedback:** Not initiating the learning and review process when the user provides relevant feedback that could improve the rules.
+*   **Scope Creep:** Updating multiple unrelated rules simultaneously or making changes that exceed the scope of the feedback received.
+*   **Unprompted Rule Changes:** Modifying rules proactively when there is no direct connection to user feedback or a learning opportunity. Rule updates should be reactive and feedback-driven.
+*   **Missing Update Confirmation:** Failing to notify the user after a rule modification has been successfully implemented following their approval.

package/template/docs/frontend-standards.md

@@ -0,0 +1,45 @@
+---
+description: TODO - one-line summary of this project's frontend standards (framework, state management, UI/testing conventions)
+globs: ["TODO - glob patterns for frontend source files, e.g. src/**/*.{ts,tsx}"]
+alwaysApply: true
+---
+
+# Frontend Project Configuration and Best Practices
+
+> This is an empty skeleton. Replace every `_TODO_` below with your project's real standards. Keep or drop sections as they apply to your stack.
+
+## Overview
+
+_TODO: one-paragraph summary of the frontend, its framework, and its overall structure._
+
+## Technology Stack
+
+_TODO: core framework, UI library, state management/data-flow approach, testing framework, key dev tools._
+
+## Project Structure
+
+_TODO: how source is organized (feature folders, components, services, etc.)._
+
+## Coding Standards
+
+_TODO: naming conventions, component conventions (function components, props typing), state management patterns, service/API layer conventions._
+
+## UI/UX Standards
+
+_TODO: design system or component library in use, form handling, navigation patterns, accessibility requirements._
+
+## Testing Standards
+
+_TODO: unit/component test conventions, end-to-end testing tool and patterns, test organization._
+
+## Configuration Standards
+
+_TODO: TypeScript config, linting rules, environment configuration._
+
+## Performance Best Practices
+
+_TODO: component optimization, bundle optimization, API call efficiency._
+
+## Development Workflow
+
+_TODO: dev scripts, code quality gates required before merge._