owflow 0.1.1 → 0.1.2

package/dist/skills/docs-manager/SKILL.md

@@ -0,0 +1,379 @@
+---
+name: docs-manager
+description: Internal engine for managing project documentation and technical standards in .owflow/docs/. Handles file operations, INDEX.md generation, and AGENTS.md integration. Invoked by flow-init, standards-update, and standards-discover skills.
+user-invocable: false
+---
+
+# Documentation Manager (Internal Engine)
+
+Internal skill that manages documentation file operations in `.owflow/docs/`. Not directly user-invocable — called by `flow-init`, `standards-update`, and `standards-discover` skills.
+
+## Core Principles
+
+- **Project documentation is source of truth** — plugin-bundled docs are baseline/reference only
+- **INDEX.md is the master map** — always kept up-to-date after changes
+- **AGENTS.md integration is mandatory** — ensures AI reads documentation
+
+## Documentation Structure
+
+```
+.owflow/docs/
+├── INDEX.md                      # Master index - READ THIS FIRST
+├── project/                      # Project-level documentation (generated by flow-init, not copied from templates)
+│   ├── vision.md                # Project vision and goals
+│   ├── roadmap.md               # Development roadmap
+│   ├── tech-stack.md            # Technology choices and rationale
+│   └── architecture.md          # System architecture (optional)
+└── standards/                    # Technical standards and conventions
+    ├── global/                  # Language-agnostic standards
+    │   ├── error-handling.md
+    │   ├── validation.md
+    │   ├── conventions.md
+    │   ├── coding-style.md
+    │   └── commenting.md
+    ├── frontend/                # Frontend-specific standards
+    │   ├── css.md
+    │   ├── components.md
+    │   ├── accessibility.md
+    │   └── responsive.md
+    ├── backend/                 # Backend-specific standards
+    │   ├── api.md
+    │   ├── models.md
+    │   ├── queries.md
+    │   └── migrations.md
+    └── testing/                 # Testing standards
+        └── test-writing.md
+```
+
+## Standard File Conventions
+
+Standard files follow the structure `standards/[category]/[topic].md`:
+
+- **Category** = domain folder (global, frontend, backend, testing, or custom)
+- **Topic file** = contains multiple related standards
+
+**Format**: Each file uses `## Topic` as the file heading, with `### Standard Name` for each individual standard. Each standard has a 1-10 line description (excluding code snippets) and an optional brief code example (under 10 lines).
+
+**Conciseness**: Standards are quick-reference conventions, not tutorials. If a file grows unwieldy, split into focused sub-topic files.
+
+**Why ### per standard**: Each standard as a discrete section makes it easier for agents to find, update, and reference individually — no need to parse bullet lists.
+
+---
+
+## Bundled Resources
+
+This skill bundles the following resources within the plugin:
+
+- **Standards Directory**: Contains baseline technical standards organized by category:
+  - `global/` - Global standards (error handling, validation, conventions, etc.)
+  - `frontend/` - Frontend-specific standards (CSS, components, accessibility, etc.)
+  - `backend/` - Backend-specific standards (API design, database, queries, etc.)
+  - `testing/` - Testing standards (test writing, coverage, etc.)
+- **INDEX.md Template**: Master template for documentation index
+
+## Location Reference
+
+- **Plugin bundles** (read-only baseline): This skill's `docs/` subdirectory within the plugin
+- **Project documentation** (source of truth): `.owflow/docs/` in the project root
+- **Project configuration**: `AGENTS.md` in the project root
+
+## Capabilities
+
+### 1. Initialize Documentation in Project
+
+Use this when a project doesn't have `.owflow/docs/` or needs documentation for the first time. This is a **one-time baseline setup** that gives the project a starting point.
+
+**IMPORTANT**: This operation accepts an optional `standards_selection` parameter (array of standard categories) to control which standards to initialize. If not provided, all standards are copied (backward compatible). It also accepts an optional `standards_source_path` parameter to copy standards from an external project instead of the bundled defaults.
+
+**What to do:**
+
+1. Check if `.owflow/docs/` exists in the project root
+2. If it exists, warn the user that initialization will overwrite existing documentation and ask for confirmation
+3. Create the directory structure based on standards_selection:
+   ```
+   .owflow/docs/
+   ├── project/
+   └── standards/
+       ├── global/      (if 'global' in standards_selection or no selection provided)
+       ├── frontend/    (if 'frontend' in standards_selection or no selection provided)
+       ├── backend/     (if 'backend' in standards_selection or no selection provided)
+       └── testing/     (if 'testing' in standards_selection or no selection provided)
+   ```
+4. Copy standards to the project's `.owflow/docs/standards/` directory. **Source selection**: If `standards_source_path` is provided, copy from that external path. Otherwise, copy from this skill's bundled `docs/standards/` directory:
+   - **Project documentation**: Do NOT copy project templates — only create the `project/` directory. Project documentation files (vision, roadmap, tech-stack, architecture) are generated by the calling skill (e.g., flow-init) using analyzer data, not copied as placeholder templates.
+   - **Standards**: Only copy selected standard categories based on standards_selection parameter:
+     - If `standards_selection` is empty or not provided: Copy ALL standards (backward compatible)
+     - If `standards_selection` is provided: Only copy specified categories
+     - Examples:
+       - `['global', 'frontend', 'testing']` → Copy only these three categories
+       - `['global', 'backend', 'testing']` → Skip frontend standards
+       - `['global', 'testing']` → Only global and testing standards
+5. Generate INDEX.md with entries for all copied documentation (see "Manage INDEX.md" operation):
+   - For skipped standard categories, add placeholder sections with "Not initialized - run standards discovery if needed"
+   - Example: If frontend standards are skipped, INDEX.md shows:
+
+     ```markdown
+     ### Frontend Standards
+
+     _Not initialized for this project. If you need frontend standards, you can:_
+
+     - _Add them manually using the docs-manager skill_
+     - _Run `/standards-discover --scope=frontend` to auto-discover_
+     ```
+
+6. **MANDATORY - Update AGENTS.md:**
+   - Check if `AGENTS.md` exists in the project root; if not, ask the user if they want to create it
+   - Add the documentation reference section (see "Manage AGENTS.md Integration" operation)
+   - Ensure it emphasizes reading INDEX.md at the beginning of any task
+7. Inform the caller about the documentation structure created
+
+**Parameters:**
+
+- `standards_selection` (optional, array of strings): Standard categories to initialize
+  - Array of category names (e.g., `['global', 'frontend', 'backend', 'testing']`). Baseline categories: global, frontend, backend, testing. Custom categories are also supported.
+  - If omitted or empty: Initialize all baseline standards (backward compatible)
+  - If provided: Only initialize specified categories (creates directories for custom ones)
+- `standards_source_path` (optional, string): Absolute path to an external standards directory (e.g., `/path/to/other-project/.owflow/docs/standards/`)
+  - If provided: Copy standards from this path instead of the bundled defaults
+  - If omitted: Copy from this skill's bundled `docs/standards/` directory (default behavior)
+
+**Result:** The project now has baseline documentation in `.owflow/docs/`, a comprehensive INDEX.md, and AGENTS.md integration that ensures AI assistance is documentation-aware. Only selected standard categories are initialized.
+
+**Important:** After this initial setup, the project's documentation becomes the source of truth. Teams should customize it for their specific needs.
+
+**Note on Skipped Standards**: If standard categories are skipped during initialization, teams can add them later using:
+
+- "Add Documentation File" operation to add specific standards
+- `/standards-discover` command to auto-discover standards from codebase
+
+---
+
+### 2. Manage INDEX.md
+
+Use this to create or update the INDEX.md file that serves as the master documentation map.
+
+**What to do:**
+
+1. Scan the `.owflow/docs/` directory structure
+2. For each documentation file found:
+   - Read the file content to extract description
+   - Determine the file's purpose and category
+   - **For technical standards**: The description MUST enumerate the specific practices/conventions documented in the file, not just a generic category description.
+3. Read `references/index-md-template.md` for the INDEX.md structure template
+4. Generate INDEX.md by populating the template with discovered files and descriptions
+5. Write the generated INDEX.md to `.owflow/docs/INDEX.md`
+6. Verify that AGENTS.md references this index (see "Manage AGENTS.md Integration" operation)
+
+**Result:** A comprehensive, up-to-date INDEX.md that provides a clear map of all project documentation.
+
+---
+
+### 3. Add Documentation File
+
+Use this to add new documentation to the project, either from plugin baseline or custom.
+
+**What to do:**
+
+1. Determine the type of documentation to add:
+   - Project documentation (vision, roadmap, tech-stack, architecture, custom)
+   - Technical standard (any category under standards/)
+2. If adding from plugin baseline:
+   - Check if the requested documentation exists in this skill's bundled `docs/` directory
+   - Copy it to the appropriate location in `.owflow/docs/`
+3. If creating custom documentation:
+   - Ask for the category (project/ or standards/category/)
+   - Ask for the filename and purpose
+   - Create a template file with appropriate frontmatter and structure
+4. Update INDEX.md to include the new documentation (see "Manage INDEX.md" operation)
+5. If this is a technical standard and corresponds to a Claude Code Skill, ensure consistency
+
+**Result:** New documentation is added to the project and indexed in INDEX.md.
+
+---
+
+### 4. Update Documentation
+
+Use this to help the user update or modify existing project documentation.
+
+**What to do:**
+
+1. Accept the documentation identifier from the user (e.g., "project/vision", "standards/global/error-handling")
+2. Check if the documentation exists in `.owflow/docs/`
+3. If the documentation exists:
+   - Read the current documentation
+   - Ask the user what they want to change or update
+   - Help them edit the documentation file directly
+   - Optionally, show them the plugin's baseline version for reference if they ask
+4. If the documentation doesn't exist:
+   - Offer to add it from the plugin baseline (see "Add Documentation File" operation)
+   - Or offer to help them create custom documentation from scratch
+5. After updating:
+   - Check if INDEX.md needs updating (if the purpose/description changed significantly)
+   - If updating tech-stack.md or architecture.md, suggest reviewing AGENTS.md for consistency
+6. For technical standards:
+   - If a corresponding Claude Code Skill exists, suggest reviewing it for consistency
+   - Standards should align with actual code patterns in the project
+
+**Result:** Documentation is updated to reflect current project state and team decisions.
+
+---
+
+### 5. Use Plugin Documentation as Reference
+
+Use this when a team wants to see the plugin's baseline documentation for reference, or reset specific docs to plugin defaults.
+
+**What to do:**
+
+1. Compare the documentation in this skill's bundled `docs/` directory with the project's `.owflow/docs/` directory to identify differences
+2. Show the user which documents differ and how they differ
+3. Explain that plugin documentation is baseline/reference only, and project documentation is superior
+4. **WARNING**: Copying plugin documentation to the project will overwrite any project-specific customizations
+5. Ask the user if they want to:
+   - View the differences for reference only (no changes)
+   - Reset specific documentation to plugin baseline (selective overwrite)
+   - Reset all documentation to plugin baseline (full overwrite - rarely recommended)
+6. If the user chooses to copy any documentation:
+   - Copy the selected files from this skill's bundled `docs/` directory to the project's `.owflow/docs/` directory
+   - Update INDEX.md to reflect any changes
+   - Review AGENTS.md for any necessary updates
+
+**Important:** This operation should be used rarely, mainly when a team wants to reset to baseline. Project documentation is the source of truth and should be maintained by the team.
+
+**Result:** User can reference plugin baseline documentation and optionally reset specific docs to plugin versions.
+
+---
+
+### 6. List Available Documentation
+
+Use this to show what documentation is bundled with this plugin and their installation status in the project.
+
+**What to do:**
+
+1. List all documentation in this skill's bundled `docs/` directory, organized by category
+2. For each bundled document:
+   - Show the category and name
+   - Check if it exists in the project at `.owflow/docs/[category]/[name].md`
+   - Show installation status (bundled only, installed, or customized)
+   - If installed, show whether it differs from the baseline (customized)
+3. Show whether INDEX.md exists and is up-to-date
+4. Show whether AGENTS.md has documentation integration
+5. Remind the user that plugin documentation is baseline/reference only, and project documentation (if installed) is the source of truth
+
+**Result:** The user sees a complete inventory of available baseline documentation and their installation status in the current project.
+
+---
+
+### 7. Manage AGENTS.md Integration
+
+Use this to ensure the project's AGENTS.md properly integrates with the documentation system, encouraging AI to read and use the documentation.
+
+**What to do:**
+
+1. Check if `AGENTS.md` exists in the project root
+2. If it doesn't exist, ask the user if they want to create it
+3. Look for a documentation reference section in AGENTS.md
+4. If the section doesn't exist or is incomplete:
+   - Read `references/claude-md-template.md` for the template
+   - Add the template section to AGENTS.md
+5. Ensure the documentation section is placed prominently in AGENTS.md (near the top)
+6. Verify that the INDEX.md path is correct and the file exists
+7. If `.owflow/docs/` doesn't exist, suggest running the initialization operation first
+
+**Result:** AGENTS.md properly integrates with the documentation system, ensuring AI assistance is documentation-aware and follows team conventions.
+
+---
+
+### 8. Validate Documentation Consistency
+
+Use this to check that documentation is consistent, up-to-date, and properly integrated.
+
+**What to do:**
+
+1. **Check structure:**
+   - Verify `.owflow/docs/` directory exists
+   - Verify all expected subdirectories exist (project/, standards/global/, etc.)
+2. **Check INDEX.md:**
+   - Verify it exists and is readable
+   - Check that all files in `.owflow/docs/` are listed in INDEX.md
+   - Check that all files listed in INDEX.md actually exist
+   - Report any orphaned files or broken references
+3. **Check AGENTS.md integration:**
+   - Verify AGENTS.md exists
+   - Verify it contains documentation reference section
+   - Verify it uses valid file reference format: @.owflow/docs/INDEX.md (with @ prefix, without backticks)
+   - Warn if using incorrect formats like `.owflow/docs/INDEX.md` or `@.owflow/docs/INDEX.md` (backticks)
+4. **Check project documentation:**
+   - Verify critical files exist (vision.md, tech-stack.md)
+   - Check if they contain placeholder text vs. actual project information
+   - Warn if critical documentation is missing or empty
+5. **Check standards consistency:**
+   - If Claude Code Skills exist, check if corresponding standards documentation exists
+   - If standards exist without skills, suggest creating skills (if appropriate)
+   - Report any inconsistencies
+6. **Generate validation report:**
+   - Summary of documentation status
+   - List of issues found
+   - Recommendations for fixes
+7. **Offer to fix issues:**
+   - Ask if the user wants to automatically fix found issues
+   - Fix missing INDEX.md entries
+   - Fix missing AGENTS.md integration
+   - Create missing directory structure
+
+**Result:** A comprehensive validation report with optional automatic fixes for common issues.
+
+---
+
+## Usage Examples
+
+**Initialize documentation in a new project:**
+
+```
+User: "Set up documentation for this project"
+Claude: [Executes Initialize Documentation - creates structure, copies baseline docs, generates INDEX.md, updates AGENTS.md, gathers project info]
+```
+
+**Update project vision:**
+
+```
+User: "I want to update our project vision to include AI-first approach"
+Claude: [Executes Update Documentation - reads current vision.md, helps user edit it, updates INDEX.md if needed]
+```
+
+**Add custom documentation:**
+
+```
+User: "Add documentation for our deployment process"
+Claude: [Executes Add Documentation File - creates custom project/deployment.md, updates INDEX.md]
+```
+
+**Reference plugin baseline:**
+
+```
+User: "Show me the plugin's baseline error handling standard"
+Claude: [Executes Use Plugin Documentation as Reference - shows plugin baseline, compares with project version, no changes unless user requests]
+```
+
+**Validate documentation:**
+
+```
+User: "Check if our documentation is complete and consistent"
+Claude: [Executes Validate Documentation Consistency - checks structure, INDEX.md, AGENTS.md integration, generates report]
+```
+
+**Manage INDEX.md:**
+
+```
+User: "Rebuild the documentation index"
+Claude: [Executes Manage INDEX.md - scans .owflow/docs/, regenerates comprehensive INDEX.md]
+```
+
+---
+
+## Important Notes
+
+- **Project documentation is source of truth** — plugin-bundled docs are baseline/reference only
+- **INDEX.md must stay current** — regenerate after any documentation change
+- **AGENTS.md integration is mandatory** — ensures AI reads documentation at task start
+- **This skill is an internal engine** — called by flow-init, standards-update, and standards-discover. Not directly user-invocable.
+- **CRITICAL: Return control after completion** — This is an internal sub-skill. After completing the requested operation, return control to the calling workflow. Do NOT treat completion of this skill as the end of the conversation turn — the parent skill has more steps to execute.

package/dist/skills/docs-manager/docs/INDEX.md

@@ -0,0 +1,199 @@
+# Documentation Index
+
+**IMPORTANT**: Read this file at the beginning of any development task to understand available documentation and standards.
+
+## Quick Reference
+
+### Project Documentation
+
+Project-level documentation covering vision, goals, architecture, and technology choices.
+
+### Technical Standards
+
+Coding standards, conventions, and best practices organized by domain.
+
+---
+
+## Project Documentation
+
+Located in `.owflow/docs/project/`
+
+### Vision (`project/vision.md`)
+
+Defines the project's mission, goals, target users, and long-term vision. Read this to understand the "why" behind the project and align development decisions with project objectives.
+
+### Roadmap (`project/roadmap.md`)
+
+Outlines development milestones, planned features, and timeline. Read this to understand project priorities and upcoming work.
+
+### Tech Stack (`project/tech-stack.md`)
+
+Documents all technologies, frameworks, libraries, and tools used in the project, with rationale for each choice. Read this before adding new dependencies or making technology decisions.
+
+### Architecture (`project/architecture.md`)
+
+Describes the system architecture, component structure, data flow, and design patterns. Read this to understand how the system is organized and how components interact.
+
+---
+
+## Technical Standards
+
+### Global Standards
+
+Located in `.owflow/docs/standards/global/`
+
+These standards apply across the entire codebase, regardless of frontend/backend context.
+
+#### Error Handling (`standards/global/error-handling.md`)
+
+Structured error types, error propagation patterns, user-facing vs internal error messages, try-catch placement guidelines, error logging conventions.
+
+#### Validation (`standards/global/validation.md`)
+
+Input validation at system boundaries, sanitization patterns, validation error message formatting, schema validation approach.
+
+#### Conventions (`standards/global/conventions.md`)
+
+Naming conventions (files, variables, functions, classes), file organization patterns, import ordering, code structure guidelines.
+
+#### Coding Style (`standards/global/coding-style.md`)
+
+Indentation and formatting rules, spacing conventions, line length limits, bracket style, consistent code readability patterns.
+
+#### Commenting (`standards/global/commenting.md`)
+
+When to comment (non-obvious logic only), documentation comment format, inline explanation guidelines, TODO/FIXME conventions.
+
+#### Minimal Implementation (`standards/global/minimal-implementation.md`)
+
+No speculative code, no unused methods, no "just in case" abstractions, YAGNI principle enforcement, lean code guidelines.
+
+---
+
+### Frontend Standards
+
+Located in `.owflow/docs/standards/frontend/`
+
+These standards apply to frontend code (UI components, client-side logic, styling).
+
+#### CSS (`standards/frontend/css.md`)
+
+CSS naming conventions, stylesheet organization, utility-first vs component styles, CSS variable usage, responsive styling patterns.
+
+#### Components (`standards/frontend/components.md`)
+
+Component structure and composition patterns, props design, lifecycle management, smart vs presentational separation.
+
+#### Accessibility (`standards/frontend/accessibility.md`)
+
+Keyboard navigation requirements, screen reader support, ARIA attribute usage, WCAG compliance level, focus management patterns.
+
+#### Responsive Design (`standards/frontend/responsive.md`)
+
+Breakpoint definitions, mobile-first approach, responsive layout patterns, touch target sizing, viewport considerations.
+
+---
+
+### Backend Standards
+
+Located in `.owflow/docs/standards/backend/`
+
+These standards apply to backend code (APIs, services, data layer).
+
+#### API Design (`standards/backend/api.md`)
+
+REST endpoint naming, request/response format conventions, versioning strategy, error response structure, pagination patterns.
+
+#### Models (`standards/backend/models.md`)
+
+Data model structure, schema conventions, business logic placement, relationship patterns, model validation rules.
+
+#### Queries (`standards/backend/queries.md`)
+
+Query optimization patterns, N+1 prevention, index usage guidelines, query builder conventions, raw query policies.
+
+#### Migrations (`standards/backend/migrations.md`)
+
+Migration naming conventions, schema change patterns, data migration approach, rollback requirements, migration testing.
+
+---
+
+### Testing Standards
+
+Located in `.owflow/docs/standards/testing/`
+
+These standards apply to all testing code (unit, integration, E2E).
+
+#### Test Writing (`standards/testing/test-writing.md`)
+
+Test naming conventions, test file organization, arrange-act-assert structure, mocking guidelines, coverage expectations, test data management.
+
+---
+
+## How to Use This Documentation
+
+1. **Start Here**: Always read this INDEX.md first to understand what documentation exists
+2. **Project Context**: Read relevant project documentation before starting work
+   - Vision and roadmap for understanding project goals
+   - Tech stack for understanding technology constraints
+   - Architecture for understanding system design
+3. **Standards**: Reference appropriate standards when writing code
+   - Global standards apply to all code
+   - Domain-specific standards (frontend/backend/testing) apply to relevant code
+4. **Keep Updated**: Update documentation when making significant changes
+   - Update project docs when goals, tech stack, or architecture changes
+   - Update standards when team conventions evolve
+   - Update INDEX.md when adding or removing documentation
+5. **Customize**: Adapt all documentation to your project's specific needs
+   - Project documentation should reflect your actual project
+   - Standards should reflect your team's conventions
+   - Both should be version-controlled and reviewed regularly
+
+## Updating Documentation
+
+### When to Update
+
+- **Project docs**: When project goals, tech stack, or architecture changes
+- **Standards**: When team conventions evolve or new patterns are adopted
+- **INDEX.md**: When adding, removing, or significantly changing documentation
+
+### How to Update
+
+1. Edit the relevant documentation file directly
+2. Update INDEX.md if the file's purpose or description changes
+3. Ensure AGENTS.md still references this INDEX.md
+4. Commit changes to version control
+5. Notify the team of significant documentation changes
+
+### Getting Help
+
+Use the Documentation Manager skill to:
+
+- Initialize documentation in a new project
+- Add new documentation files
+- Update existing documentation
+- Validate documentation consistency
+- Manage INDEX.md automatically
+- Ensure AGENTS.md integration
+
+---
+
+## Documentation Priority
+
+When making development decisions, follow this priority order:
+
+1. **Project documentation** in `.owflow/docs/` (highest priority)
+   - Represents team decisions and project-specific requirements
+2. **Code patterns** visible in the codebase
+   - Shows how the team actually implements things
+3. **User's direct instructions**
+   - Specific guidance for the current task
+4. **General best practices** (lowest priority)
+   - Default to industry standards when no specific guidance exists
+
+**The documentation in `.owflow/docs/` represents team decisions and should be followed unless the user explicitly overrides them.**
+
+---
+
+**Last Generated**: [Automatically updated by Documentation Manager]
+**Maintained by**: Documentation Manager skill

package/dist/skills/docs-manager/docs/standards/backend/api.md

@@ -0,0 +1,25 @@
+## API Design
+
+### RESTful Principles
+Use resource-based URLs with appropriate HTTP methods (GET, POST, PUT, PATCH, DELETE).
+
+### Consistent Naming
+Use lowercase, hyphenated or underscored names consistently across endpoints.
+
+### Versioning
+Implement versioning (URL path or headers) to manage breaking changes.
+
+### Plural Nouns
+Use plural nouns for resources (`/users`, `/products`).
+
+### Limited Nesting
+Keep URL nesting to 2-3 levels maximum for readability.
+
+### Query Parameters
+Use query parameters for filtering, sorting, and pagination.
+
+### Proper Status Codes
+Return appropriate HTTP status codes (200, 201, 400, 404, 500).
+
+### Rate Limit Headers
+Include rate limit information in response headers.

package/dist/skills/docs-manager/docs/standards/backend/migrations.md

@@ -0,0 +1,22 @@
+## Database Migrations
+
+### Reversible
+Always implement rollback methods for safe migration reversals.
+
+### Small and Focused
+Keep each migration to a single logical change.
+
+### Zero-Downtime Awareness
+Consider deployment order and backward compatibility for high-availability systems.
+
+### Separate Schema and Data
+Keep schema changes separate from data migrations for safer rollbacks.
+
+### Careful Indexing
+Create indexes on large tables carefully, using concurrent options when available.
+
+### Descriptive Names
+Use names that indicate what the migration does.
+
+### Version Control
+Commit migrations; never modify existing ones after deployment.

package/dist/skills/docs-manager/docs/standards/backend/models.md

@@ -0,0 +1,25 @@
+## Models
+
+### Clear Naming
+Use singular names for models and plural for tables (or follow framework conventions).
+
+### Timestamps
+Include created and updated timestamps for auditing and debugging.
+
+### Database Constraints
+Enforce data rules at the database level (NOT NULL, UNIQUE, foreign keys).
+
+### Appropriate Types
+Choose data types that match purpose and size requirements.
+
+### Index Foreign Keys
+Index foreign key columns and frequently queried fields.
+
+### Multi-Layer Validation
+Validate at both model and database levels for defense in depth.
+
+### Clear Relationships
+Define relationships with appropriate cascade behaviors and naming.
+
+### Practical Normalization
+Balance normalization with query performance needs.

package/dist/skills/docs-manager/docs/standards/backend/queries.md

@@ -0,0 +1,22 @@
+## Database Queries
+
+### Parameterized Queries
+Always use parameterized queries or ORM methods; never interpolate user input into SQL.
+
+### Avoid N+1
+Use eager loading or joins to fetch related data in one query.
+
+### Select Only Needed Columns
+Request only the columns you need rather than SELECT *.
+
+### Index Strategic Columns
+Index columns used in WHERE, JOIN, and ORDER BY clauses.
+
+### Transactions
+Wrap related operations in transactions to maintain consistency.
+
+### Query Timeouts
+Set timeouts to prevent runaway queries from impacting performance.
+
+### Cache Expensive Queries
+Cache results of complex or frequent queries when appropriate.