sickn33/agentic-awesome-skills/documentation-and-adrs

# ADR-001: Use PostgreSQL for primary database
 
## Status
Proposed | Accepted | Superseded by ADR-XXX | Deprecated
 
## Date
2025-01-15
 
## Context
We need a primary database for the task management application. Key requirements:
-Relational data model (users, tasks, teams with relationships)
-ACID transactions for task state changes
-Support for full-text search on task content
-Managed hosting available (for small team, limited ops capacity)
 
## Decision
Use PostgreSQL with Prisma ORM.
 
## Alternatives Considered
 
### MongoDB
-Pros: Flexible schema, easy to start with
-Cons: Our data is inherently relational; would need to manage relationships manually
-Rejected: Relational data in a document store leads to complex joins or data duplication
 
### SQLite
-Pros: Zero configuration, embedded, fast for reads
-Cons: Limited concurrent write support, no managed hosting for production
-Rejected: Our measured concurrent-write requirements exceed the selected deployment's constraints; assess SQLite for the actual workload before rejecting it
 
### MySQL
-Pros: Mature, widely supported
-Cons: PostgreSQL has better JSON support, full-text search, and ecosystem tooling
-Rejected: PostgreSQL is the better fit for our feature requirements
 
## Consequences
-Prisma provides type-safe database access and migration management
-We can use PostgreSQL's full-text search instead of adding Elasticsearch
-Team needs PostgreSQL knowledge (standard skill, low risk)
-Hosting on managed service (Supabase, Neon, or RDS)

PROPOSED → ACCEPTED → (SUPERSEDED or DEPRECATED)

// BAD: Restates the code
// Increment counter by 1
counter += 1;
// GOOD: Explains non-obvious intent
// This simple counter resets its window on the first request after expiry.
// It is not a sliding-window limiter; assess bursts near the boundary.
if (now - windowStart > WINDOW_SIZE_MS) {
  counter = 0;
  windowStart = now;
}

// Don't comment self-explanatory code
function calculateTotal(items: CartItem[]): number {
  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
}
// Don't leave TODO comments for things you should just do now
// TODO: add error handling  ← Just add it
// Don't leave commented-out code
// const oldImplementation = () => { ... }  ← Delete it, git has history

/**
 * IMPORTANT: This function must be called before the first render.
 * If called after hydration, it causes a flash of unstyled content
 * because the theme context isn't available during SSR.
 *
 * See ADR-003 for the full design rationale.
 */
export function initializeTheme(theme: Theme): void {
  // ...
}

/**
 * Creates a new task.
 *
 * @param input - Task creation data (title required, description optional)
 * @returns The created task with server-generated ID and timestamps
 * @throws {ValidationError} If title is empty or exceeds 200 characters
 * @throws {AuthenticationError} If the user is not authenticated
 *
 * @example
 * const task = await createTask({ title: 'Buy groceries' });
 * console.log(task.id); // "task_abc123"
 */
export async function createTask(input: CreateTaskInput): Promise<Task> {
  // ...
}

paths:
  /api/tasks:
    post:
      summary: Create a task
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaskInput'
      responses:
        '201':
          description: Task created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '422':
          description: Validation error

# Project Name
 
One-paragraph description of what this project does.
 
## Quick Start
1.Clone the repo
2.Install dependencies: `npm install`
3.Set up environment: `cp .env.example .env`
4.Run the dev server: `npm run dev`
 
## Commands
| Command | Description |
|---------|-------------|
| `npm run dev` | Start development server |
| `npm test` | Run tests |
| `npm run build` | Production build |
| `npm run lint` | Run linter |
 
## Architecture
Brief overview of the project structure and key design decisions.
Link to ADRs for details.
 
## Contributing
How to contribute, coding standards, PR process.

# Changelog
 
## [1.2.0] - 2025-01-20
### Added
-Task sharing: users can share tasks with team members (#123)
-Email notifications for task assignments (#124)
 
### Fixed
-Duplicate tasks appearing when rapidly clicking create button (#125)
 
### Changed
-Task list now loads 50 items per page (was 20) for better UX (#126)