Skill: badideal-2046/specvibe (version 1.0.0)

--- name: SpecVibe description: A world-class, spec-driven development framework for building production-ready, AI-native applications. Use for any new project to ensure adherence to the most advanced 2026 best practices in architecture, security, testing, and deployment. --- # SpecVibe: The AI-Native Development Framework This skill provides a universal, seven-stage framework for developing production-ready, AI-native applications. It enforces a **[REDACTED_SECRET]** mindset, ensuring that every aspect of the project is defined, testable, secure, and documented before and during implementation, following the most advanced 2026 community best practices from Google, GitHub, and Thoughtworks. ## Core Philosophy - **Intent is the Source of Truth**: The specification (`spec.md`) is the primary artifact. Code is the last-mile implementation of that intent. - **Human-AI Collaboration**: Follow the **Delegate/Review/Own** model at every stage to maximize efficiency and maintain quality. - **Iterate in Small, Validated Chunks**: Break down work into the smallest possible units, test them, and commit frequently. Never let the AI generate large, monolithic blocks of code. - **Automate Everything**: Use tests, linters, CI/CD, and automated documentation to build a robust quality assurance system. ## The Seven Stages of AI-Native Development Follow these stages sequentially. Each stage has a **Quality Gate**—a set of questions you must answer before proceeding—and a clear **Delegate/Review/Own** model for human-AI collaboration. | Stage | Focus | Key Activities | Reference Guides | | :--- | :--- | :--- | :--- | | **1. Specify** | User Journey & Requirements | Create `spec.md` defining user stories, goals, and non-functional requirements. | `references/00-specvibe.md` | | **2. Plan** | Technical Architecture | Create `PLAN.md`, select tech stack, define architecture, and break down the spec into tasks. | `references/02-backend.md`, `references/03-frontend.md` | | **3. Test** | Behavior-Driven Definition | Write failing unit, integration, and E2E tests based on the spec and plan. | `references/05-testing.md` | | **4. Implement** | Code Generation & Refinement | Write (or generate) code to make the tests pass, following a chunked iteration strategy. | `references/08-ai-collaboration.md` | | **5. Review** | Quality & Security Assurance | Conduct automated and human code reviews, focusing on security, logic, and maintainability. | `references/04-security.md` | | **6. Document** | Knowledge Capture | Automatically generate and manually refine user and developer documentation. | `references/09-documentation.md` | | **7. Deploy** | CI/CD & Observability | Containerize, set up CI/CD pipelines, and implement full observability. | `references/06-devops.md`, `references/07-error-handling.md` | --- ## Stage 1: Specify - The Intent **Goal**: Define *what* to build and *why* in a structured `spec.md`. - **Delegate**: Ask the AI to interview you about the project goals and generate a draft `spec.md` using the `templates/spec-template.md`. - **Review**: Check if the spec accurately captures all user stories, edge cases, and success metrics. - **Own**: The final approval of the user requirements and business goals. ### Quality Gate 1: Specification Review - *Does the `spec.md` clearly define the user, their problem, and the proposed solution?* - *Are non-functional requirements (performance, security, accessibility) listed?* - *Is the scope well-defined and unambiguous for an AI to understand?* --- ## Stage 2: Plan - The Blueprint **Goal**: Translate the `spec.md` into a concrete technical plan. - **Delegate**: Feed `spec.md` to the AI and ask it to generate a `PLAN.md` detailing the architecture, data models (using `references/01-schema-and-types.md`), API contracts (using `templates/openapi-template.yaml`), and a task breakdown. - **Review**: Assess the proposed tech stack, architecture, and task list for feasibility and alignment with best practices. - **Own**: The final architectural decisions and technology choices. ### Quality Gate 2: Plan Review - *Is the chosen architecture appropriate for the project's scale and requirements?* - *Is the API contract complete and consistent with the data models?* - *Are the tasks small, independent, and logically sequenced?* --- ## Stage 3: Test - The Safety Net **Goal**: Define the application's behavior through a comprehensive, failing test suite. - **Delegate**: Ask the AI to generate a full suite of tests (unit, integration, E2E) based on `spec.md` and `PLAN.md`. Refer to `references/05-testing.md`. - **Review**: Ensure tests cover all user stories, API endpoints, and critical business logic. Check for meaningful assertions. - **Own**: The definition of "done" for each feature, as represented by the tests. ### Quality Gate 3: Test Suite Review - *Does every feature in the spec have corresponding tests?* - *Do all tests currently fail for the correct reasons?* --- ## Stage 4: Implement - The Engine Room **Goal**: Write clean, efficient code that makes all tests pass. - **Delegate**: Instruct the AI to implement one task at a time, feeding it the relevant spec, plan, and failing test. Use the "chunked iteration" strategy from `references/08-ai-collaboration.md`. - **Review**: After each small chunk, review the generated code for correctness and style. Do not wait for the entire feature to be complete. - **Own**: The responsibility for committing each validated chunk of code to version control. ### Quality Gate 4: Implementation Review - *Do all tests for the implemented task now pass?* - *Is the code clean, readable, and consistent with the project's style guide?* - *Has the change been committed to Git with a clear message?* --- ## Stage 5: Review - The Quality Shield **Goal**: Ensure the implemented code is secure, robust, and maintainable. - **Delegate**: Automate security scans (SAST, DAST, dependency checking) in CI. Use an AI agent to perform a preliminary code review based on `references/04-security.md` (OWASP 2025). - **Review**: A human developer must perform a final review, focusing on logic, architecture, and subtle bugs that AI might miss. - **Own**: The final approval (LGTM) to merge the code into the main branch. ### Quality Gate 5: Code Review - *Does the code pass all automated security and quality checks?* - *Has a human engineer reviewed and approved the changes?* --- ## Stage 6: Document - The Knowledge Base **Goal**: Create clear, comprehensive documentation for both users and developers. - **Delegate**: Use AI to generate initial drafts of API documentation from the OpenAPI spec, and user guides from the `spec.md`. Refer to `references/09-documentation.md`. - **Review**: Edit the AI-generated content for clarity, accuracy, and tone. Add diagrams and examples. - **Own**: The final, published documentation that serves as the official source of information. ### Quality Gate 6: Documentation Review - *Is the API documentation accurate and complete?* - *Is the user guide easy for a non-technical person to understand?* --- ## Stage 7: Deploy - The Launchpad **Goal**: Automate deployment and ensure the application is observable and reliable in production. - **Delegate**: Ask the AI to generate Dockerfiles, CI/CD pipeline configurations (e.g., GitHub Actions), and infrastructure-as-code scripts. Refer to `references/06-devops.md`. - **Review**: Verify the deployment scripts, container configurations, and monitoring setup (`references/07-error-handling.md`). - **Own**: The production environment and the ultimate responsibility for uptime and reliability. ### Quality Gate 7: Production Readiness Review - *Can the application be deployed and rolled back with a single command?* - *Is comprehensive, structured logging (OpenTelemetry) in place?* - *Are alerting and monitoring configured for key performance indicators?*

path: CONTRIBUTING.md
content: # Contributing to SpecVibe

First off, thank you for considering contributing. Your help is essential for keeping this framework great.

## How Can I Contribute?

### Reporting Bugs

- Ensure the bug was not already reported by searching on GitHub under [Issues](https://github.com/badideal-2046/SpecVibe/issues ).
- If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/badideal-2046/SpecVibe/issues/new ). Be sure to include a clear title, a specific description, and as much relevant information as possible.

### Suggesting Enhancements

- Open a new issue to discuss your enhancement suggestion. Please provide a clear and detailed explanation of the feature you'd like to see and why it's needed.

### Pull Requests

1.  Fork the repository and create your branch from `main`.
2.  Make your changes. Ensure your code adheres to the project's style and principles.
3.  Update the documentation if you are changing or adding functionality.
4.  Issue that pull request!

## Styleguides

- All text content should be clear, concise, and professional.
- Commit messages should be descriptive and follow conventional standards.

We look forward to your contributions!


path: README.md
content: # SpecVibe

**An executable, spec-driven framework for building production-ready AI-native applications.**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg )](https://opensource.org/licenses/MIT ) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg )](CONTRIBUTING.md) [![ClawHub](https://img.shields.io/badge/ClawHub-v1.0.0-blue )](https://clawhub.ai/skills/badideal-2046/SpecVibe ) 

SpecVibe is not just a collection of guidelines; it is a complete, structured, and executable framework designed to be integrated directly into modern AI coding assistants like Claude Code, OpenClaw, and Cursor. It enforces a rigorous, seven-stage development workflow, ensuring every project is architected, built, tested, and deployed according to 2026 industry best practices.

## Why SpecVibe?

Most AI development guides are passive documents. SpecVibe is an **active framework** that becomes part of your AI assistant's core logic. It bridges the gap between ad-hoc prompting ("vibe coding") and professional software engineering.

| Feature | Standard Guides | SpecVibe Framework |
| :--- | :--- | :--- |
| **Core Philosophy** | Vague best practices | Executable **Spec-Driven** workflow |
| **Coverage** | Focus on one area (e.g., security) | **Full Lifecycle**: Specify, Plan, Test, Implement, Review, Document, Deploy |
| **Integration** | Manual copy-pasting | **Direct Integration** with Claude Code, OpenClaw, etc. |
| **Security Standard** | General advice | Aligned with **OWASP Top 10:2025** |
| **AI Collaboration** | Basic prompt tips | **Delegate/Review/Own** model at every stage |
| **Completeness** | Missing key areas | Includes a11y, i18n, API versioning, and more |

## The 7-Stage Workflow

SpecVibe structures development into seven distinct stages, each with a clear goal and a quality gate.

1.  **Specify**: Define user journeys and requirements in a structured `spec.md`.
2.  **Plan**: Create the technical architecture, data models, and API contracts.
3.  **Test**: Write a comprehensive, failing test suite before writing any code.
4.  **Implement**: Generate code in small, validated chunks to make the tests pass.
5.  **Review**: Perform automated and human code reviews for quality and security.
6.  **Document**: Generate and refine user and developer documentation.
7.  **Deploy**: Automate deployment with CI/CD and ensure full observability.

## Getting Started

Choose the integration method for your preferred AI coding assistant.

### For Claude Code

1.  Clone this repository into your project's `.claude/skills/` directory.
2.  Create a `CLAUDE.md` file in your project root and import the framework:

    ```markdown
    # Project Development Framework
    @import .claude/skills/SpecVibe/SKILL.md
    ```

### For OpenClaw

1.  Clone this repository into `~/.openclaw/skills/`.
2.  OpenClaw will automatically detect and load SpecVibe as a core skill.

### For Cursor / Other Editors

1.  Clone this repository into your project's `.cursor-rules/` (or equivalent) directory.
2.  Use the `cursorrules-template.md` to set up your root rules file, instructing the AI to follow the SpecVibe framework.

## What's Inside?

-   **`SKILL.md`**: The core executable workflow that guides the AI.
-   **11 Reference Guides**: In-depth best practices for every domain, from backend architecture to accessibility.
-   **4 Templates**: Ready-to-use templates for specifications, API contracts, deployment checklists, and AI rule files.

## Contributing

Contributions are welcome. Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to report bugs, suggest features, or submit pull requests.

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.


path: references/00-specvibe.md
content: # Reference: 00 - The SpecVibe Methodology

This document outlines the core principles of the SpecVibe methodology, which forms the foundation of this entire Skill. This approach, synthesized from the 2025-2026 best practices of industry leaders like Google, GitHub, and Thoughtworks, treats the **specification as the executable source of truth**.

## From Schema-First to Spec-Driven

While **Schema-First** is a good practice focusing on data models and API contracts, **Spec-Driven** is a more holistic evolution. It encompasses the entire lifecycle, from user requirements to deployment, all anchored to a living specification document (`spec.md`).

> "We’re moving from ‘code is the source of truth’ to ‘intent is the source of truth.’ With AI the specification becomes the source of truth and determines what gets built." — GitHub [1]

## The Four-Phase Cycle (Specify, Plan, Tasks, Implement)

Inspired by GitHub's Spec Kit [1], the core implementation loop revolves around four distinct phases, designed for maximum clarity and AI effectiveness.

1.  **Specify**: The process begins not with code, but with a detailed, structured description of the *what* and the *why*. This `spec.md` file captures user journeys, goals, and non-functional requirements. It is the foundational document that guides all subsequent work.

2.  **Plan**: The `spec.md` is fed to an AI to generate a `PLAN.md`. This technical blueprint defines the *how*—architecture, technology stack, data models, and API contracts. This is where human expertise is crucial for making strategic architectural decisions.

3.  **Tasks**: The AI then breaks down the `spec.md` and `PLAN.md` into a series of small, discrete, and testable tasks. Each task should be a self-contained unit of work that can be implemented and validated in isolation.

4.  **Implement**: The AI, guided by a human developer, tackles one task at a time. This **"chunked iteration"** is critical. It prevents the AI from generating large, unmanageable blocks of code and allows for rapid, iterative feedback and course correction.

## The Delegate/Review/Own Model

To ensure quality and maintain control in an AI-native workflow, we adopt OpenAI's Delegate/Review/Own model [2] for human-AI collaboration at every stage:

| Role | Responsibility |
| :--- | :--- |
| **Delegate** | Tasks that can be fully handed off to the AI for a first draft (e.g., generating boilerplate code, writing initial tests, creating a draft `spec.md`). |
| **Review** | Tasks where the AI's output must be carefully scrutinized by a human expert (e.g., reviewing architectural suggestions, validating security logic, checking test coverage). |
| **Own** | Strategic decisions and ultimate responsibilities that remain entirely with the human developer (e.g., final architectural choices, approving a merge to production, defining business goals). |

This model ensures that the AI is used as a powerful force multiplier, while the human developer remains the accountable owner of the final product.

## The Spec as a Living Artifact

Crucially, the `spec.md` is not a static document that is written once and forgotten. It is a **living artifact** that evolves with the project. When requirements change, the first step is always to update the `spec.md`. This change then cascades through the plan, tasks, and implementation, ensuring that the codebase always reflects the current intent.

This approach, as described by Martin Fowler, moves towards a **"spec-anchored"** or even **"spec-as-source"** model of development [3].

---

### References

[1] GitHub. (2025, September 2). *Spec-driven development with AI: Get started with a new open source toolkit*. The GitHub Blog.
[2] OpenAI. (2025). *Building an AI-Native Engineering Team*. OpenAI Codex Guides.
[3] Fowler, M. (2025, October 15). *Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl*. MartinFowler, M. (2025, October 15). *Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl*.


path: references/01-schema-and-types.md
content: # Reference: 01 - Schema, Types, and API Contracts

This guide covers the principles of defining data models and API contracts, which form the blueprint of the application.

## 1. Data Modeling: The Single Source of Truth

All data structures MUST be defined before any implementation. A shared `schema.ts` or similar file is the single source of truth for the entire application's data model.

### Principles

- **Clarity and Precision**: Use clear, descriptive names for interfaces, types, and enums.
- **Normalization**: Avoid data duplication. Use relationships to link entities.
- **Scalability**: Consider future needs when designing models.

### Best Practices

1.  **Use TypeScript Interfaces**: Define each database table or logical entity as a TypeScript `interface`.

    ```typescript
    // Example: A User entity
    export interface User {
      id: string; // UUID
      email: string; // Unique
      name: string | null;
      role: UserRole;
      createdAt: Date;
    }
    ```

2.  **Use Enums for Controlled Vocabularies**: For fields with a fixed set of possible values, always use an `enum`.

    ```typescript
    export enum UserRole {
      ADMIN = 'ADMIN',
      JUDGE = 'JUDGE',
      VIEWER = 'VIEWER',
    }
    ```

3.  **Document JSON/unstructured Columns**: If using a JSON/JSONB column, define its structure with a dedicated interface.

    ```typescript
    export interface UserPreferences {
      theme: 'dark' | 'light';
      notifications: {
        email: boolean;
        push: boolean;
      };
    }

    export interface User {
      // ... other fields
      preferences: UserPreferences; // Stored in a JSONB column
    }
    ```

## 2. API Contract: OpenAPI Specification

The API contract is a formal, machine-readable definition of your API. We use the **OpenAPI 3.0** standard.

### Principles

- **Contract-First**: The OpenAPI spec is written *before* the API code.
- **Consumer-Centric**: Design the API from the perspective of the frontend or third-party developer who will use it.
- **Completeness**: The spec must define all endpoints, parameters, request bodies, responses (including errors), and authentication methods.

### Best Practices

1.  **Use the Template**: Start with the `templates/openapi-template.yaml` file provided in this skill.

2.  **Define Reusable Components**: For common data structures like `User`, `Error`, or paginated responses, define them once in the `components/schemas` section and reference them using `$ref`.

    ```yaml
    components:
      schemas:
        Error:
          type: object
          properties:
            code: { type: string }
            message: { type: string }
    paths:
      /users/{userId}:
        get:
          responses:
            '404':
              description: User not found
              content:
                application/json:
                  schema:
                    $ref: '#/components/schemas/Error'
    ```

3.  **Clearly Document Responses**: Define all possible HTTP status code responses for each endpoint, especially common errors like `400` (Validation Error), `401` (Unauthorized), `403` (Forbidden), and `404` (Not Found).

## 3. API Versioning

APIs evolve. A clear versioning strategy is mandatory to avoid breaking changes for consumers.

- **Method**: Use **URL-based versioning** (e.g., `/api/v1/users`, `/api/v2/users`). It is the most explicit and widely understood method.
- **When to Version**: Increment the version number only for **breaking changes** (e.g., removing a field, changing a data type, altering an endpoint's path). Adding new fields or endpoints is non-breaking and does not require a version bump.
- **Deprecation Policy**: Clearly document your deprecation policy. When a new version (e.g., `v2`) is released, the old version (`v1`) should be maintained for a documented period (e.g., 6 months) before being decommissioned.

## 4. Type Safety Across Stacks

To eliminate an entire class of bugs, we ensure type safety from the database to the UI.

- **Backend**: Use an ORM like Prisma that generates type-safe clients from your database schema.
- **Frontend**: **Do not write API fetching code by hand.** Use a tool like `openapi-typescript-codegen` to automatically generate a fully-typed API client from your `openapi.yaml` file. This ensures that if the backend API changes, the frontend code will fail to compile, catching errors at build time, not runtime.


path: references/02-backend.md
content: # SpecVibe Reference: Backend Development

This guide outlines the standards for building robust, scalable, and maintainable backend services.

## 1. Architecture: Layered & Decoupled

A layered architecture separates concerns, making the codebase easier to understand, test, and maintain. Follow this structure:

1.  **Controller/Router Layer**: The entry point for HTTP requests. Its only job is to parse the request (headers, body, params), call the appropriate service, and send the response. **No business logic here.**
2.  **Service Layer**: Contains the core business logic. It orchestrates calls to the data access layer and other services. It knows *what* to do, but not *how* the data is stored.
3.  **Data Access Layer (DAL/Repository)**: Responsible for all communication with the database. This is the only layer that should contain database-specific code (e.g., Prisma, SQL queries).

```
Request -> Controller -> Service -> Data Access Layer -> Database
```

## 2. API Implementation

- **Follow the Contract**: Your API implementation MUST strictly adhere to the `openapi.yaml` specification. All request parameters, body structures, and response formats must match the contract.
- **Middleware for Common Tasks**: Use middleware for cross-cutting concerns like authentication, logging, and error handling. This keeps your endpoint handlers clean and focused on their specific task.

## 3. Database & ORM

- **Use an ORM**: Use a modern ORM like Prisma or Drizzle. This provides type safety and abstracts away much of the boilerplate SQL.
- **Migrations are Mandatory**: NEVER change the database schema manually in production. All schema changes MUST be managed through migration files generated by the ORM (`prisma migrate dev`). These files must be committed to version control.
- **Optimize Queries**: 
    - **Indexing**: Add indexes to columns that are frequently used in `WHERE` clauses, `JOIN`s, or `ORDER BY` operations. Use compound indexes for queries that filter on multiple columns. This is the single most important performance optimization.
    - **N+1 Problem**: Be aware of the N+1 query problem when fetching related data in a loop. Use the ORM's features for eager loading (e.g., Prisma's `include` or `select`) to fetch all necessary data in a constant number of queries.
    - **Connection Pooling**: Ensure your database connection pool is properly configured to handle the expected concurrent traffic.

## 4. Error Handling

Refer to `references/07-error-handling.md` for detailed guidelines. The key principle is to handle errors gracefully and provide meaningful feedback to the client.

## 5. Configuration

- **Environment Variables**: All configuration, especially secrets (API keys, database URLs, JWT secrets), MUST be loaded from environment variables. DO NOT hardcode them.
- **Use a `.env` file** for local development, and ensure a `.env.example` file is committed to the repository to document required variables.


path: references/03-frontend.md
content: # SpecVibe Reference: Frontend Development

This guide provides standards for building modern, performant, and maintainable user interfaces.

## 1. Architecture: Component-Based

- **Componentization**: Break down the UI into small, reusable, and single-purpose components.
- **Container vs. Presentational Components**: 
    - **Container Components**: Are concerned with *how things work*. They manage state, fetch data, and pass data down to presentational components. They don't have many styles.
    - **Presentational Components**: Are concerned with *how things look*. They receive data and callbacks via props and render UI. They don't know where the data comes from.

## 2. State Management

- **Start Simple**: For most applications, React's built-in hooks (`useState`, `useReducer`, `useContext`) are sufficient. Don't introduce a complex state management library (like Redux) unless you have a clear need for it (e.g., complex, deeply nested state shared across many unrelated components).
- **Server State vs. UI State**: Separate state that comes from the server (e.g., user data, product lists) from state that is local to the UI (e.g., whether a modal is open, the value of a form input). Use a dedicated library like React Query or SWR to manage server state. These libraries handle caching, re-fetching, and optimistic updates automatically.

## 3. Data Fetching

- **Use a Generated Client**: As mentioned in `01-schema-and-types.md`, generate a type-safe API client from your OpenAPI spec. This is non-negotiable.
- **Centralize API Calls**: Create a dedicated `services` or `api` directory to house all data fetching logic. Components should not make direct `fetch` calls.
- **Handle All States**: Every data request has multiple states. Your UI must gracefully handle all of them:
    - **`isLoading`**: Show a loading spinner or skeleton screen.
    - **`isError`**: Show a user-friendly error message with an option to retry.
    - **`isSuccess` with data**: Render the data.
    - **`isSuccess` with no data**: Show an empty state message (e.g., "No projects found. Create your first one!").

## 4. User Experience (UX)

- **Optimistic Updates**: For actions that are likely to succeed (e.g., liking a post, deleting an item), update the UI immediately *before* the API call completes. If the API call fails, roll back the change and show an error message. This makes the application feel much faster.
- **Accessibility (a11y)**: Build for everyone. Use semantic HTML, ensure all interactive elements are keyboard-navigable, and provide `alt` text for images.
- **Performance**: 
    - **Code Splitting**: Use dynamic `import()` to lazy-load components that are not needed for the initial render (e.g., modals, routes).
    - **Memoization**: Use `React.memo`, `useMemo`, and `useCallback` to prevent unnecessary re-renders of expensive components.
    - **Image Optimization**: Serve images in modern formats (like WebP) and at the correct size.

## 5. Styling

- **Use a Framework**: Use a utility-first CSS framework like Tailwind CSS. This encourages consistency and avoids writing custom CSS.
- **Design System**: Establish a consistent design system for colors, typography, spacing, and shadows. Store these values in your `tailwind.config.js` file and reuse them.


path: references/04-security.md
content: # Reference: 04 - Security (OWASP 2025 Edition)

Security is not a feature; it's a prerequisite. This guide aligns with the **OWASP Top 10 for 2025** [1] and the principle of **Zero Trust Architecture** ("never trust, always verify") [2]. Every line of code should be written with a security-first mindset.

## The Delegate/Review/Own Model for Security

- **Delegate**: Use automated tools (SAST, DAST, dependency scanners) in your CI/CD pipeline to catch common vulnerabilities. Ask the AI to scan for basic security flaws.
- **Review**: A human must review all security-critical code, especially authentication, authorization, and input validation logic. Do not blindly trust AI-generated security code.
- **Own**: The ultimate responsibility for the application's security posture rests with the development team.

## OWASP Top 10: 2025 Checklist

This checklist must be reviewed before any production deployment.

| ID | Risk | Mitigation Strategy |
| :--- | :--- | :--- |
| **A01** | **Broken Access Control** | Implement role-based access control (RBAC). Deny by default. Verify permissions on every request. Use Row-Level Security (RLS) for multi-tenant applications. |
| **A02** | **Security Misconfiguration** | Use Infrastructure as Code (IaC) to manage configuration. Remove all default passwords and unused features. Harden HTTP headers (CSP, HSTS, X-Frame-Options). |
| **A03** | **Software Supply Chain Failures** | Use a dependency scanner (e.g., `npm audit`, Snyk) to find known vulnerabilities in your libraries. Pin dependencies to specific versions. Verify the integrity of packages. |
| **A04** | **Cryptographic Failures** | Use modern, industry-standard encryption (TLS 1.3, Argon2 for hashing). Never roll your own crypto. Store secrets in a dedicated vault. |
| **A05** | **Injection** | Use prepared statements and parameterized queries for all database access. Sanitize user input before rendering in the UI. |
| **A06** | **Insecure Design** | Security must be part of the design phase. Use threat modeling to identify potential risks before writing code. |
| **A07** | **Authentication Failures** | Enforce multi-factor authentication (MFA). Implement strong password policies. Use rate limiting to prevent brute-force attacks. |
| **A08** | **Software or Data Integrity Failures** | Use digital signatures or checksums to verify the integrity of data and software updates. Protect your CI/CD pipeline from unauthorized access. |
| **A09** | **Security Logging and Alerting Failures** | Log all security-relevant events (logins, failed logins, access denials). Set up automated alerts for suspicious activity. Ensure logs do not contain sensitive data (PII, tokens). |
| **A10** | **Mishandling of Exceptional Conditions** | Ensure that error messages do not leak sensitive information (stack traces, internal paths). Implement robust, structured error handling that fails securely (fail-closed, not fail-open). |

## Practical Implementation

### 1. Authentication (AuthN): Who are you?

- **Use Standard Protocols**: Use battle-tested standards like OAuth 2.0 or OpenID Connect (OIDC). For simple token-based auth, use JSON Web Tokens (JWT).
- **Secure JWTs**: Use a strong, randomly generated secret key (at least 256 bits) loaded from an environment variable. Set a short expiration time for access tokens (e.g., 15 minutes) and use refresh tokens for longer sessions.
- **Password Security**: NEVER store passwords in plain text. Use a strong, slow hashing algorithm like Argon2 or bcrypt.

### 2. Authorization (AuthZ): What can you do?

- **Principle of Least Privilege**: Users should only have the minimum permissions necessary.
- **Implement Middleware**: Authorization checks should be implemented as middleware that runs before your API endpoint logic.
- **Role-Based Access Control (RBAC)**: Assign roles to users (e.g., `ADMIN`, `JUDGE`, `VIEWER`) and define permissions for each role.
- **Row-Level Security (RLS)**: For multi-tenant applications, ensure that users from one organization cannot access data from another.

### 3. Input Validation: Trust Nothing

**All data coming from the client is untrusted.** This is the most important rule of web security.

- **Validate at the Edge**: Validate all incoming data at the API boundary before it reaches your business logic.
- **Use a Schema-Based Library**: Use a library like **Zod** or **Joi** to define schemas for your request bodies, parameters, and query strings.
- **Prevent Injection Attacks**: Use an ORM or parameterized queries to prevent SQL injection. Sanitize all user-provided data to prevent Cross-Site Scripting (XSS).

### 4. Secrets Management

- **NEVER Hardcode Secrets**: API keys, database credentials, JWT secrets, and any other sensitive information must NEVER be committed to version control.
- **Use Environment Variables**: Load all secrets from environment variables.
- **Use a Secret Manager**: For production, use a dedicated secret management service (e.g., AWS Secrets Manager, Google Secret Manager, HashiCorp Vault).

---

### References

[1] OWASP. (2025). *OWASP Top 10:2025*. OWASP Foundation.
[2] OWASP. *Zero Trust Architecture Cheat Sheet*. OWASP Cheat Sheet Series.


path: references/05-testing.md
content: # SpecVibe Reference: Testing

Automated testing is the foundation of building reliable software. It provides a safety net that allows you to refactor code and add new features with confidence.

## 1. The Testing Pyramid

Structure your tests according to the testing pyramid:

- **Unit Tests (Base)**: The majority of your tests. They are small, fast, and test a single function or component in isolation.
- **Integration Tests (Middle)**: Test how multiple units work together. For example, testing a service layer method that calls the data access layer.
- **End-to-End (E2E) Tests (Top)**: A small number of tests that simulate a real user journey through the entire application, from the UI to the database.

## 2. Unit Tests

- **Focus**: Test a single, isolated piece of logic.
- **Mocks and Stubs**: Use mocking libraries (like Vitest's `vi.mock`) to replace external dependencies (e.g., database calls, API requests) with predictable fakes. This ensures your test is isolated.
- **Coverage**: Aim for high unit test coverage (>80%) on all critical business logic.

```typescript
// Example: Unit test for a simple utility function
import { expect, test } from 'vitest';
import { slugify } from './utils';

test('should convert a string to a slug', () => {
  expect(slugify('Hello World!')).toBe('hello-world');
});
```

## 3. Integration Tests

- **Focus**: Test the interaction between multiple components or layers.
- **Real Dependencies**: Use a real test database (e.g., a separate Docker container) for integration tests. This provides much higher confidence than using mocks.
- **API Testing**: The most valuable integration tests for a web application are API tests. Use a library like `supertest` to make HTTP requests to your running application and assert the responses.

```typescript
// Example: API integration test
import { expect, test } from 'vitest';
import request from 'supertest';
import { app } from './app'; // Your Express app

test('GET /users/:id should return a user', async () => {
  const response = await request(app).get('/users/123');
  expect(response.status).toBe(200);
  expect(response.body.id).toBe('123');
});
```

## 4. End-to-End (E2E) Tests

- **Focus**: Simulate a complete user workflow.
- **Use a Framework**: Use a modern E2E testing framework like Playwright or Cypress. These tools control a real browser to interact with your application just like a user would.
- **Test the Happy Path**: E2E tests are slow and brittle. Focus on testing the most critical user journeys (e.g., user registration, creating a project, completing a purchase).

```typescript
// Example: Playwright E2E test
import { test, expect } from '@playwright/test';

test('should allow a user to sign up', async ({ page }) => {
  await page.goto('/signup');
  await page.fill('input[name="email"]', '[REDACTED_SECRET]');
  await page.fill('input[name="password"]', 'password123');
  await page.click('button[type="submit"]');
  await expect(page.locator('h1')).toHaveText('Welcome!');
});
```

## Best Practices

- **Test-Driven Development (TDD)**: Write a failing test *before* you write the implementation code. This forces you to think about requirements and edge cases first.
- **Run Tests in CI**: All tests MUST be run automatically in your CI/CD pipeline on every commit. A broken build should prevent code from being merged or deployed.


path: references/06-devops.md
content: # Reference: 06 - DevOps, CI/CD, and Version Control

DevOps is the culture and practice of automating the processes between software development and IT teams, in order that they can build, test, and release software faster and more reliably.

## 1. Version Control: Git Discipline

Version control is the backbone of a reliable development process, especially in AI-assisted workflows where frequent rollbacks may be necessary.

- **Branching Strategy**: Use **GitHub Flow**:
    1.  Create a new branch from `main` for every new feature or bugfix.
    2.  Commit your changes to that branch.
    3.  Open a Pull Request (PR) when you are ready for feedback.
    4.  After the PR is reviewed and approved, merge it into `main`.
    5.  The `main` branch is always deployable.
- **Commit Messages**: Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification (e.g., `feat: add user registration endpoint`, `fix: correct score calculation logic`).
- **Frequent Commits**: In AI-assisted development, commit after every successful, validated chunk of work. This creates frequent "save points" that you can roll back to if the AI introduces a regression in a later step. Think of it as a "Ctrl+S" for your entire project state.
- **Rollback Strategy**: Before asking the AI to make a large or risky change, always create a new branch or tag the current commit. If the change goes wrong, you can instantly revert to the known-good state.

## 2. Continuous Integration (CI)

CI is the practice of automatically building and testing your code every time a change is committed.

- **Automate Everything**: Your CI pipeline (e.g., using GitHub Actions, GitLab CI) should automatically:
    1.  Install dependencies.
    2.  Run linters to check code style.
    3.  Run all unit and integration tests.
    4.  Run security scans (dependency audit, SAST).
    5.  Build the application (e.g., create a Docker image).
- **Fail Fast**: If any step fails, the build should be marked as broken. Merging to `main` should be blocked if the CI pipeline fails.

## 3. Continuous Deployment (CD)

CD is the practice of automatically deploying your application to production after it has passed all the tests in the CI pipeline.

- **Infrastructure as Code (IaC)**: Define and manage your infrastructure using code (e.g., Terraform, Pulumi, or Docker Compose). This makes your infrastructure reproducible and version-controlled.
- **Containerization**: Package your application into a container using Docker. This ensures consistency across environments.
- **Blue-Green or Canary Deployments**: Use advanced deployment strategies to release new versions with zero downtime and the ability to quickly roll back.

## 4. Monitoring & Observability (OpenTelemetry)

Once your application is in production, you need to know what it is doing. The modern standard for observability is **OpenTelemetry** [1], which provides a unified framework for collecting three types of telemetry data:

| Pillar | Description | Tool Example |
| :--- | :--- | :--- |
| **Traces** | Track a single request as it flows through all services in your system. | Jaeger, Zipkin |
| **Metrics** | Numerical measurements of your system's health (e.g., request latency, error rate, CPU usage). | Prometheus + Grafana |
| **Logs** | Detailed, structured records of events within your application. Refer to `references/07-error-handling.md`. | ELK Stack, Datadog |

- **Health Checks**: Expose a `/health` endpoint that your deployment environment can use to check if your application is running correctly.
- **Alerting**: Set up alerts to notify you immediately if a critical metric crosses a threshold (e.g., if the error rate exceeds 5%).

---

### References

[1] OpenTelemetry. (2025). *OpenTelemetry Documentation*. opentelemetry.io.


path: references/07-error-handling.md
content: # Reference: 07 - Error Handling and Observability

Robust error handling and clear observability are critical for maintaining a healthy production application. This guide also addresses **OWASP A10:2025 (Mishandling of Exceptional Conditions)** [1].

## 1. Error Handling

- **Fail Gracefully, Fail Securely**: Never let an unexpected error crash the entire application. Use `try...catch` blocks for operations that can fail. When an error occurs, the system should **fail closed** (deny access, return a generic error) rather than **fail open** (grant access, expose internal details).
- **Custom Error Classes**: Create custom error classes that extend the base `Error` class.

  ```typescript
  class AppError extends Error {
    constructor(public statusCode: number, public code: string, message: string) {
      super(message);
      this.name = 'AppError';
    }
  }
  class NotFoundError extends AppError {
    constructor(resource: string) {
      super(404, 'NOT_FOUND', `${resource} not found`);
    }
  }
  class ValidationError extends AppError {
    constructor(details: string[]) {
      super(400, 'VALIDATION_ERROR', details.join(', '));
    }
  }
  ```

- **Standardized Error Responses**: Your API should return errors in a consistent, predictable format. Refer to the `Error` schema in your `openapi.yaml`.

  ```json
  {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email address",
    "details": ["The email field must be a valid email."]
  }
  ```

- **Never Expose Internal Details**: Error messages returned to the client must NEVER include stack traces, internal file paths, database query details, or any other information that could be exploited by an attacker. Log the full details server-side, but return a generic message to the client.

## 2. Structured Logging

Logging is the most fundamental tool for understanding what is happening inside your application.

- **Structured Logging**: Do not log plain text strings. Log JSON objects. This makes your logs machine-readable and allows you to easily search, filter, and analyze them.

  ```javascript
  // Bad
  logger.info('User ' + userId + ' logged in.');

  // Good
  logger.info({ userId, event: 'USER_LOGIN', traceId: req.traceId }, 'User logged in.');
  ```

- **Log Levels**: Use different log levels to indicate the severity of an event:
    - **`DEBUG`**: Detailed information for debugging during development.
    - **`INFO`**: Normal application behavior (e.g., user login, API request).
    - **`WARN`**: A potential problem that does not prevent the application from functioning.
    - **`ERROR`**: An error that caused an operation to fail. This requires attention.
    - **`FATAL`**: An error that is causing the application to crash.
- **Correlation IDs**: Assign a unique `traceId` (or `requestId`) to every incoming request and include it in all log entries for that request. This allows you to trace a single user action through all the services and log entries it touches. This is a core concept of **distributed tracing** in OpenTelemetry.
- **Security Logging (OWASP A09)**: Log all security-relevant events: successful and failed logins, access control failures, input validation failures, and administrative actions. Ensure logs do NOT contain sensitive data (passwords, tokens, PII).

## 3. Error Reporting

- **Automated Error Reporting**: Integrate an error reporting service (like Sentry or Bugsnag) into your application. This will automatically capture all unhandled exceptions, group them, and notify you.
- **Include Context**: When reporting an error, include as much context as possible, such as the user ID, request ID, and application version. This makes debugging much easier.

---

### References

[1] OWASP. (2025). *OWASP Top 10:2025 - A10: Mishandling of Exceptional Conditions*. OWASP Foundation.


path: references/08-ai-collaboration.md
content: # Reference: 08 - Advanced AI Collaboration (2026 Edition)

Working with an AI pair programmer requires a different style of communication than working with a human. This guide provides advanced patterns for maximizing the effectiveness of AI-assisted development, based on 2026 best practices [1].

## 1. The "Big Daddy" Rule: Elevate the AI's Role

At the beginning of a development session, set the AI's role to be more than just a coder—make it an architect and a critic.

**Good Prompt:**
> "You are my expert AI pair programmer, acting as a principal engineer. We are building a production-grade application. I expect you to think critically, identify potential issues, challenge my assumptions, suggest better architectural patterns, and ask clarifying questions *before* you write code."

## 2. Multi-Model Strategy: "Model Musical Chairs"

Different models excel at different tasks. Do not use a single model for everything. A state-of-the-art workflow involves using a portfolio of models:

| Task | Recommended Model Type | Example |
| :--- | :--- | :--- |
| **Planning & Reasoning** | High-reasoning, large context window | `gpt-4.1-mini`, `gemini-2.5-flash` |
| **Code Generation** | Fast, code-optimized | `gpt-4.1-nano` |
| **Code Review & Analysis** | High-accuracy, large context window | `gemini-2.5-flash` |
| **Documentation** | Creative, fluent language | `gpt-4.1-mini` |

## 3. Context Packing: Give the AI Perfect Memory

The AI's output is only as good as its input. Provide it with all the necessary context using automated tools.

- **Use Context Management Tools**: Use tools like **gitingest**, **repo2txt**, or **Context7 MCP** to automatically package the relevant parts of your codebase into the prompt.
- **Reference the Spec**: Always anchor your requests to the `spec.md` and `PLAN.md`.

**Good Prompt:**
> "I need to implement Task #5 from `PLAN.md` ('Create user registration endpoint'). Here are the relevant files: `spec.md`, `PLAN.md`, `references/04-security.md`, and the failing test `tests/integration/auth.test.ts`. Please generate the code to make the test pass."

## 4. The "Quality Gate" Prompt

After the AI generates a block of code, force it to self-correct by using a "Quality Gate" prompt.

**Good Prompt:**
> "Stop. Before I use this code, please review it against our development standards. Specifically, check for the following:
> 1.  **Security**: Does this align with our `references/04-security.md` (OWASP 2025)?
> 2.  **Error Handling**: Are all fallible operations handled according to `references/07-error-handling.md`?
> 3.  **Testing**: Does this change require a new unit test?
>
Please provide the corrected code if you find any issues."

## 5. The "Reverse Question" Technique

Challenge the AI to think more deeply about the code it has written.

**Good Prompts:**
- `"What are the three biggest risks with the code you just wrote? How can we mitigate them?"`
- `"Imagine this code needs to handle 1000 requests per second. What would be the performance bottleneck?"`
- `"What is one alternative approach to solving this problem, and what are its pros and cons compared to your solution?"`

---

### References

[1] Osmani, A. (2025, December 19). *My LLM coding workflow going into 2026*. Medium.


path: references/09-documentation.md
content: # Reference: 09 - Documentation

Code is read more often than it is written. Good documentation is not an afterthought; it is a core part of a maintainable and scalable project.

## The Delegate/Review/Own Model for Documentation

- **Delegate**: Use AI to generate the first draft of all documentation. This includes API reference documentation from OpenAPI specs, README files from `spec.md`, and code comments.
- **Review**: A human must review all AI-generated documentation for accuracy, clarity, and tone. The goal is to make the documentation helpful and easy to understand.
- **Own**: The development team owns the quality and completeness of the documentation.

## Types of Documentation

### 1. API Documentation

- **Source**: The `openapi.yaml` file is the single source of truth.
- **Generation**: Use a tool like **Redoc** or **Swagger UI** to automatically generate a beautiful, interactive API reference website from your OpenAPI spec.
- **CI/CD**: This generation and deployment should be part of your CI/CD pipeline.

### 2. Developer Documentation

- **README.md**: The root `README.md` should be a concise entry point to the project. It should explain what the project is, why it exists, and how to get it running locally. Use the `templates/readme-template.md` as a starting point.
- **Architectural Decision Records (ADRs)**: For significant architectural decisions (e.g., choosing a database, deciding on a microservices pattern), create a short markdown file in a `/docs/adr` directory. This provides context for future developers on *why* a decision was made.

### 3. User Documentation

- **Source**: The `spec.md` file, which contains the user journeys and goals.
- **Format**: Can be a simple set of markdown files, a GitBook, or a dedicated knowledge base.
- **Content**: Should be written for a non-technical audience. Focus on how to use the application to solve their problems.

### 4. Code Comments

- **Good Code is Self-Documenting**: Strive to write code that is so clear it doesn't need comments.
- **Comment the *Why*, not the *What***: Do not write comments that explain what the code is doing. A developer can read the code to understand that. Write comments to explain *why* the code is doing something, especially if the reason is not obvious (e.g., a workaround for a library bug, a specific business rule).

    ```typescript
    // Bad comment: what
    // Increment i by 1
    i++;

    // Good comment: why
    // We need to increment the counter here to account for the off-by-one
    // error in the legacy data import script.
    i++;
    ```


path: references/10-accessibility-and-i18n.md
content: # Reference: 10 - Accessibility (a11y) and Internationalization (i18n)

Building for a global audience means ensuring everyone can use your application, regardless of ability or language.

## 1. Accessibility (a11y)

Accessibility is the practice of making your web applications usable by as many people as possible. It is a legal and ethical requirement in many countries.

- **Standard**: Adhere to the **Web Content Accessibility Guidelines (WCAG) 2.1**, aiming for Level AA compliance.
- **Semantic HTML**: Use HTML elements for their correct purpose. Use `<nav>`, `<main>`, `<aside>`, `<header>`, `<footer>`, and `<button>`, not just `<div>` and `<span>`.
- **Keyboard Navigation**: Ensure all interactive elements (links, buttons, form inputs) are focusable and usable with only a keyboard.
- **Alternative Text**: Provide descriptive `alt` text for all images.
- **ARIA Roles**: Use Accessible Rich Internet Applications (ARIA) roles and attributes where necessary to provide additional context to screen readers, but prioritize using correct semantic HTML first.
- **Automated Testing**: Use tools like **axe** in your CI/CD pipeline to automatically catch common accessibility violations.

## 2. Internationalization (i18n)

Internationalization is the process of designing your application so that it can be adapted to various languages and regions without engineering changes.

- **Use a Library**: Use a dedicated i18n library for your frontend framework (e.g., `react-i18next` for React).
- **Extract All Strings**: Do not hardcode any user-visible strings in your code. Store them in locale-specific JSON files.

    ```javascript
    // Bad: Hardcoded string
    return <button>Submit</button>;

    // Good: Using i18n library
    import { useTranslation } from 'react-i18next';
    const { t } = useTranslation();
    return <button>{t('common.submit')}</button>;
    ```

    ```json
    // public/locales/en/common.json
    {
      "submit": "Submit"
    }

    // public/locales/es/common.json
    {
      "submit": "Enviar"
    }
    ```

- **Formatting**: Use the `Intl` object in JavaScript for formatting dates, times, numbers, and currencies according to the user's locale.


path: templates/cursorrules-template.md
content: ```markdown
# This file contains rules for the AI assistant (e.g., Cursor).

## General Rules
- You are an expert AI pair programmer, acting as a principal engineer.
- You must follow the project's SpecVibe workflow.
- Before writing code, always ask for the relevant `spec.md` and `PLAN.md` files.
- Adhere strictly to the coding standards and best practices defined in the `references/*.md` files.
- Write clean, modular, and well-documented code.
- Always include comprehensive tests for any new code you write.

## File-Specific Rules

### For `*.ts` and `*.tsx` files:
- **No `any`**: Do not use the `any` type. Define explicit types for all variables and function signatures.
- **Error Handling**: All functions that can fail (e.g., API calls, file I/O) must be wrapped in `try...catch` blocks or return a `Result` type.
- **Imports**: Keep imports organized and remove unused ones.

### For `*.test.ts` files:
- Follow the Arrange-Act-Assert pattern.
- Use descriptive names for your tests.

### For `*.md` files:
- Use clear and concise language.
- Format text using standard Markdown syntax.
```
## Self-Correction Prompt

After generating code, always run this internal self-correction prompt:
"Stop. Before I use this code, please review it against our development standards. Specifically, check for the following:
1.  **Security**: Does this align with our `references/04-security.md` (OWASP 2025)?
2.  **Error Handling**: Are all fallible operations handled according to `references/07-error-handling.md`?
3.  **Testing**: Does this change require a new unit test?
4.  **Type Safety**: Did you use `any`?
Please provide the corrected code if you find any issues."
```
## Reverse Question Prompt

After self-correction, run this internal reverse question prompt:
"What are the three biggest risks with the code you just wrote? How can we mitigate them?"
```


path: templates/openapi-template.yaml
content: openapi: 3.0.3
info:
  title: [Your API Title]
  description: [A brief, clear description of what your API does.]
  version: 1.0.0
servers:
  - url: http://localhost:8000/v1
    description: Development Server

paths:
  /health:
    get:
      summary: Health Check
      description: Check if the service is running.
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok

components:
  schemas:
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: A short, machine-readable error code.
          example: NOT_FOUND
        message:
          type: string
          description: A human-readable error message.
        details:
          type: array
          items:
            type: string
          description: Optional array of specific validation errors.

  responses:
    Unauthorized:
      description: Authentication information is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The user does not have permission to perform this action.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

security:
  - BearerAuth: []

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT


path: templates/pre-deploy-checklist.md
content: # Pre-Deployment Checklist

Before deploying to production, review the entire codebase against this checklist.

## Security
- [ ] All API keys, database credentials, and other secrets are loaded from environment variables (or a secret manager) and are NOT in version control.
- [ ] All API endpoints are protected by authentication and authorization middleware.
- [ ] Row-Level Security is implemented and tested to prevent data leakage between tenants.
- [ ] All user input is validated on the backend using a schema library (e.g., Zod).
- [ ] Dependencies have been scanned for known vulnerabilities (`npm audit`).

## Testing
- [ ] All unit and integration tests pass in the CI pipeline.
- [ ] Test coverage for critical business logic is above 80%.
- [ ] E2E tests for the main user journeys pass reliably.

## Performance
- [ ] Database queries are optimized with appropriate indexes.
- [ ] N+1 query problems have been identified and fixed.
- [ ] Frontend bundle size has been analyzed and code-splitting is implemented for large components/routes.
- [ ] Images are optimized and served in modern formats.

## Observability & Error Handling
- [ ] Structured logging is implemented for all key events and errors.
- [ ] An error reporting service (e.g., Sentry) is integrated.
- [ ] A `/health` check endpoint is implemented.

## Environment & Configuration
- [ ] A `.env.example` file exists and is up-to-date.
- [ ] The production environment has been configured with all necessary environment variables.
- [ ] Database migrations are handled automatically by the deployment script/pipeline.


path: templates/spec-template.md
content: # Project Specification: [Project Name]

**Version**: 1.0
**Date**: {{CURRENT_DATE}}

## 1. Overview

- **What is this project?** (A one-sentence description)
- **Why are we building it?** (The business problem or user need)
- **Who is it for?** (The target user persona)

## 2. User Stories

*(Format: As a [user type], I want to [action] so that [benefit].)*

- **US-001**: As a new user, I want to register for an account so that I can access the application.
- **US-002**: As a logged-in user, I want to ...

## 3. Non-Functional Requirements (NFRs)

| Category | Requirement |
| :--- | :--- |
| **Performance** | - The API response time for P95 must be under 200ms.<br>- The web application must achieve a Lighthouse score of over 90 for Performance. |
| **Security** | - Must comply with OWASP Top 10 2025.<br>- All user data must be encrypted at rest and in transit. |
| **Accessibility** | - Must achieve WCAG 2.1 Level AA compliance. |
| **Scalability** | - The system must be able to handle 10,000 concurrent users. |

## 4. Out of Scope

- What we are explicitly *not* building at this time.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)