contextos-agents 2.1.0 → 2.1.1

package/catalog/skills/generators/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: document-generator
+description: >
+  Generates project documentation from a single idea. Creates PRD, Architecture,
+  Database, API, UI, Roadmap, Tasks, Decision Records, and Project Graph
+  using templates. Supports incremental updates.
+---
+
+# document-generator
+
+## Overview
+
+Automated technical documentation generator. Transforms initial project ideas and specs into comprehensive PRDs, architecture schemas, API contracts, database ERDs, and roadmap task breakdowns.
+
+## When to Use
+
+Activate during project kickoff (ctx init), new service scaffolding, or when generating baseline technical specs from high-level user requirements.
+
+## Rules & Patterns
+
+You generate project documentation from a user's idea. Use the templates in `templates/` as the structure for each document.
+
+## Workflows & CLI Commands
+
+### Project Initialization (`contextos init`)
+
+Full project initialization. From one user prompt, generate foundational documentation:
+
+1. Ask clarifying questions (see context-os SKILL.md)
+2. Select profile and skill pack
+3. Generate documents in this order:
+   - `docs/PRD.md` - Product Requirements (from template)
+   - `docs/ARCHITECTURE.md` - System Architecture
+   - `docs/DATABASE.md` - Database Schema
+   - `docs/API.md` - API Specification (optional, when backend API layer is present)
+   - `docs/UI.md` - UI/UX Specification (optional, when UI layer is present)
+   - `docs/ROADMAP.md` - Development Roadmap
+   - `docs/TASKS.md` - Task Breakdown
+   - `docs/PROJECT_GRAPH.md` - Project Graph
+4. Create `docs/decisions/` directory for future ADRs
+5. Generate agent configuration via Adapters skill (`contextos export all`)
+
+### Incremental Updates
+
+When project requirements or schemas change:
+
+1. Identify which documents are affected
+2. Update only affected documents
+3. Show diff of changes to user
+4. Update Project Graph if structure changed
+
+### Task Breakdown & Planning (`contextos resolve` & `/plan`)
+
+Generate vertical development tasks from existing PRD and architecture:
+
+1. Read `docs/PRD.md` and `docs/ARCHITECTURE.md`
+2. Run `contextos resolve "<task description>"` to resolve minimal required skills
+3. Break modules into vertical features and tasks (< 2 hours each)
+4. Estimate complexity (S/M/L/XL)
+5. Output to `docs/TASKS.md` or task implementation plan
+
+## Template Usage
+
+Each template contains:
+
+- **Section headers** - required sections for the document
+- **Placeholder prompts** - `{{description}}` markers that guide content generation
+- **Examples** - sample content to illustrate the expected format
+- **Validation rules** - what must be present for the document to be valid
+
+When generating a document:
+
+1. Read the template
+2. Fill in each section based on the user's idea and clarifying answers
+3. Replace all `{{placeholders}}` with real content
+4. Remove the template comments (lines starting with `<!-- -->`)
+5. Validate: ensure all required sections are present
+
+## Document Dependencies
+
+```
+PRD.md
+  ├── ARCHITECTURE.md
+  │     ├── DATABASE.md
+  │     ├── API.md
+  │     └── DEPLOYMENT.md
+  ├── UI.md
+  ├── ROADMAP.md
+  │     └── TASKS.md
+  └── PROJECT_GRAPH.md
+```
+
+When updating a parent document, check if child documents need updates too.
+
+
+## Code Examples
+
+See `EXAMPLES.md` for detailed code examples.
+
+## Validation Checklist
+
+What to verify during the review phase before completing the task.
+
+## Common Mistakes
+
+Anti-patterns and things to explicitly avoid. See `TROUBLESHOOTING.md`.
+
+## Integration Notes
+
+How this skill interacts with other skills.

package/catalog/skills/generators/TROUBLESHOOTING.md

@@ -0,0 +1,7 @@
+# generators Troubleshooting & Common Mistakes
+
+## 1. Generic Boilerplate Generation
+
+- **Symptom**: Generated documentation contains placeholders like [Insert DB Name here].
+- **Root Cause**: Generating docs before clarifying core project constraints.
+- **Fix**: Run the interview-me protocol before generating technical documentation.

package/catalog/skills/generators/VALIDATION.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "rules_followed": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "rules_followed"
+  ]
+}

package/catalog/skills/generators/skill.yaml

@@ -0,0 +1,22 @@
+schemaVersion: 2
+name: generators
+category: engineering
+type: compiler
+description: >
+  Generates complete project documentation (PRD, Architecture, Database, API, UI,
+  Roadmap, Tasks) from ideas and templates with incremental update support.
+version: 1.0.0
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json
+  - templates/API.md
+  - templates/ARCHITECTURE.md
+  - templates/DATABASE.md
+  - templates/DECISION.md
+  - templates/PRD.md
+  - templates/PROJECT_GRAPH.md
+  - templates/ROADMAP.md
+  - templates/TASKS.md
+  - templates/UI.md

package/catalog/skills/generators/templates/API.md

@@ -0,0 +1,77 @@
+# {{Project Name}} - API Specification
+
+## Base URL
+
+`{{base_url}}` (e.g., `https://api.example.com/v1`)
+
+## Authentication
+
+{{auth_method}} (e.g., Bearer token via JWT)
+
+## Endpoints
+
+### {{Module Name}}
+
+#### `{{METHOD}} {{path}}`
+
+{{description}}
+
+**Request:**
+
+```json
+{{request_body}}
+```
+
+**Response (200):**
+
+```json
+{{response_body}}
+```
+
+**Errors:**
+
+| Code | Description |
+| --- | --- |
+| 400 | {{bad_request_reason}} |
+| 401 | Unauthorized |
+| 404 | {{not_found_reason}} |
+
+---
+
+## Error Format
+
+All errors follow this format:
+
+```json
+{
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "Human-readable message",
+    "details": {}
+  }
+}
+```
+
+## Pagination
+
+```json
+{
+  "data": [...],
+  "pagination": {
+    "page": 1,
+    "per_page": 20,
+    "total": 100,
+    "total_pages": 5
+  }
+}
+```
+
+## Rate Limiting
+
+- {{rate_limit}} requests per {{window}}
+- Headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
+
+## Versioning
+
+- URL-based: `/v1/`, `/v2/`
+- Breaking changes require new version

package/catalog/skills/generators/templates/ARCHITECTURE.md

@@ -0,0 +1,70 @@
+# {{Project Name}} - System Architecture
+
+## Architecture Overview
+<!-- High-level architecture description and diagram -->
+
+```
+{{architecture_diagram}}
+```
+
+## Tech Stack
+
+| Layer | Technology | Reason |
+| --- | --- | --- |
+| Frontend | {{e.g., Next.js + React}} | {{reason}} |
+| Backend | {{e.g., Node.js + Express}} | {{reason}} |
+| Database | {{e.g., PostgreSQL}} | {{reason}} |
+| Cache | {{e.g., Redis}} | {{reason}} |
+| Auth | {{e.g., JWT + OAuth2}} | {{reason}} |
+| Hosting | {{e.g., Vercel + Railway}} | {{reason}} |
+
+## System Components
+
+### {{Component 1 Name}}
+
+- **Responsibility:** {{what it does}}
+- **Interfaces:** {{what it exposes}}
+- **Dependencies:** {{what it depends on}}
+
+### {{Component 2 Name}}
+
+- **Responsibility:** {{what it does}}
+- **Interfaces:** {{what it exposes}}
+- **Dependencies:** {{what it depends on}}
+
+## Data Flow
+
+```
+User → Frontend → API Gateway → Service Layer → Database
+                                      ↓
+                                 Cache Layer
+```
+
+## Directory Structure
+
+```
+{{project_root}}/
+├── src/
+│   ├── modules/           # Feature modules
+│   │   ├── {{module_1}}/
+│   │   └── {{module_2}}/
+│   ├── shared/            # Shared utilities
+│   ├── config/            # Configuration
+│   └── types/             # Type definitions
+├── tests/
+├── docs/
+└── infrastructure/
+```
+
+## Security Architecture
+<!-- Authentication, authorization, data protection -->
+
+## Scalability Considerations
+<!-- How will this scale? What are the bottlenecks? -->
+
+## Error Handling Strategy
+<!-- How are errors propagated, logged, and reported? -->
+
+## Key Architectural Decisions
+<!-- Reference to ADRs in docs/decisions/ -->
+- See `docs/decisions/` for all architectural decisions with rationale

package/catalog/skills/generators/templates/DATABASE.md

@@ -0,0 +1,42 @@
+# {{Project Name}} - Database Schema
+
+## Database Engine
+
+{{e.g., PostgreSQL 16}}
+
+## Entity Relationship Diagram
+
+```
+{{ER_diagram}}
+```
+
+## Tables
+
+### {{table_name}}
+
+| Column | Type | Constraints | Description |
+| --- | --- | --- | --- |
+| id | UUID | PK, DEFAULT gen_random_uuid() | Primary key |
+| {{column}} | {{type}} | {{constraints}} | {{description}} |
+| created_at | TIMESTAMPTZ | NOT NULL, DEFAULT NOW() | Creation timestamp |
+| updated_at | TIMESTAMPTZ | NOT NULL, DEFAULT NOW() | Last update timestamp |
+
+**Indexes:**
+
+- `idx_{{table}}_{{column}}` ON ({{column}})
+
+**Relations:**
+
+- {{table_name}}.{{fk_column}} → {{related_table}}.id
+
+## Migrations Strategy
+<!-- How are schema changes applied? -->
+- Tool: {{e.g., Prisma Migrate, Alembic, Knex}}
+- Naming: `YYYYMMDD_HHMMSS_description`
+- Rule: Never modify existing migrations, always create new ones
+
+## Seed Data
+<!-- What data needs to exist for the app to work? -->
+
+## Performance Considerations
+<!-- Indexes, query optimization, connection pooling -->

package/catalog/skills/generators/templates/DECISION.md

@@ -0,0 +1,46 @@
+# ADR-{{number}}: {{Decision Title}}
+
+**Date:** {{YYYY-MM-DD}}
+**Status:** {{proposed | accepted | deprecated | superseded}}
+**Affected modules:** {{module_1}}, {{module_2}}
+
+## Decision
+
+{{What was decided, in one sentence.}}
+
+## Why
+
+{{The reasoning behind this decision. What problem does it solve?}}
+
+## Alternatives Considered
+
+### {{Alternative 1}}
+
+- **Pros:** {{advantages}}
+- **Cons:** {{disadvantages}}
+- **Why rejected:** {{reason}}
+
+### {{Alternative 2}}
+
+- **Pros:** {{advantages}}
+- **Cons:** {{disadvantages}}
+- **Why rejected:** {{reason}}
+
+## Tradeoffs
+
+| Aspect | Gain | Cost |
+| --- | --- | --- |
+| {{aspect_1}} | {{what_we_gain}} | {{what_we_lose}} |
+| {{aspect_2}} | {{what_we_gain}} | {{what_we_lose}} |
+
+## Impact
+
+- **Code changes:** {{what files/modules are affected}}
+- **Performance:** {{performance impact}}
+- **Team:** {{learning curve, tooling changes}}
+- **Reversibility:** {{easy | moderate | hard | irreversible}}
+
+## References
+
+- {{link_1}}
+- {{link_2}}

package/catalog/skills/generators/templates/PRD.md

@@ -0,0 +1,67 @@
+# {{Project Name}} - Product Requirements Document
+
+## Overview
+<!-- One paragraph describing what this product does and who it's for -->
+{{project_description}}
+
+## Problem Statement
+<!-- What problem does this solve? Why does it need to exist? -->
+
+## Target Users
+<!-- Who will use this? Define user personas -->
+
+| Persona | Description | Key Needs |
+| --- | --- | --- |
+| {{persona_1}} | {{description}} | {{needs}} |
+| {{persona_2}} | {{description}} | {{needs}} |
+
+## Core Features
+
+### Must Have (P0)
+<!-- Features required for MVP -->
+- [ ] {{feature_1}}
+- [ ] {{feature_2}}
+
+### Should Have (P1)
+<!-- Features for v1.0 -->
+- [ ] {{feature_3}}
+- [ ] {{feature_4}}
+
+### Nice to Have (P2)
+<!-- Future features -->
+- [ ] {{feature_5}}
+
+## User Flows
+
+### {{Primary Flow Name}}
+
+```
+Step 1: {{action}}
+Step 2: {{action}}
+Step 3: {{action}}
+```
+
+## Non-Functional Requirements
+
+| Requirement | Target |
+| --- | --- |
+| Performance | {{e.g., page load < 2s}} |
+| Availability | {{e.g., 99.9%}} |
+| Security | {{e.g., OWASP Top 10 compliance}} |
+| Accessibility | {{e.g., WCAG 2.1 AA}} |
+| Scalability | {{e.g., 10K concurrent users}} |
+
+## Constraints
+<!-- Technical, business, or timeline constraints -->
+- {{constraint_1}}
+- {{constraint_2}}
+
+## Success Metrics
+<!-- How will we measure success? -->
+- {{metric_1}}
+- {{metric_2}}
+
+## Out of Scope
+<!-- What this project explicitly does NOT do -->
+- {{exclusion_1}}
+- {{exclusion_2}}

package/catalog/skills/generators/templates/PROJECT_GRAPH.md

@@ -0,0 +1,56 @@
+# {{Project Name}} - Project Graph
+
+## Project
+
+```yaml
+name: "{{project_name}}"
+type: {{webapp | api | mobile | cli | saas | crm | ecommerce}}
+profile: {{startup | enterprise | mvp | hackathon}}
+pack: {{skill_pack_name}}
+```
+
+## Modules
+
+### {{module_name}}
+
+```yaml
+module: {{module_name}}
+description: "{{what this module does}}"
+features:
+  - {{feature_1}}
+  - {{feature_2}}
+files:
+  - src/modules/{{module_name}}/**
+skills: [{{skill_1}}, {{skill_2}}]
+depends_on: [{{other_module}}]
+```
+
+---
+
+<!-- Repeat for each module -->
+
+## Module Dependency Graph
+
+```
+{{module_1}} ──depends──▶ {{module_2}}
+     │
+     └──depends──▶ {{module_3}}
+```
+
+## File → Module Mapping
+
+| File Pattern | Module | Skills |
+| --- | --- | --- |
+| `src/modules/{{module}}/**` | {{module}} | {{skills}} |
+| `src/shared/**` | shared | {{skills}} |
+| `src/config/**` | config | - |
+| `tests/**` | testing | testing |
+| `docs/**` | docs | - |
+
+## Feature → Task Mapping
+
+### {{Feature Name}} `[{{module}}]`
+
+- [ ] {{task_1}} → `{{file_path}}`
+- [ ] {{task_2}} → `{{file_path}}`
+- [ ] {{task_3}} → `{{file_path}}`

package/catalog/skills/generators/templates/ROADMAP.md

@@ -0,0 +1,51 @@
+# {{Project Name}} - Roadmap
+
+## Vision
+
+{{one_sentence_vision}}
+
+## Milestones
+
+### v0.1 - MVP ({{target_date}})
+
+**Goal:** {{what_mvp_achieves}}
+
+- [ ] {{feature_1}}
+- [ ] {{feature_2}}
+- [ ] {{feature_3}}
+
+**Success criteria:** {{how_to_know_mvp_is_done}}
+
+---
+
+### v0.2 - {{milestone_name}} ({{target_date}})
+
+**Goal:** {{what_this_milestone_achieves}}
+
+- [ ] {{feature_4}}
+- [ ] {{feature_5}}
+
+---
+
+### v1.0 - Production ({{target_date}})
+
+**Goal:** {{what_production_means}}
+
+- [ ] {{feature_6}}
+- [ ] {{feature_7}}
+- [ ] Performance optimization
+- [ ] Security audit
+- [ ] Documentation
+
+---
+
+## Backlog
+<!-- Future ideas not yet scheduled -->
+- {{idea_1}}
+- {{idea_2}}
+
+## Risks
+
+| Risk | Impact | Mitigation |
+|---|---|---|
+| {{risk_1}} | {{high/medium/low}} | {{mitigation}} |

package/catalog/skills/generators/templates/TASKS.md

@@ -0,0 +1,43 @@
+# {{Project Name}} - Tasks
+
+## Current Sprint: {{sprint_name}}
+
+### In Progress
+
+- [ ] {{task}} `[{{module}}]` `[{{size: S/M/L/XL}}]`
+
+### To Do
+
+- [ ] {{task}} `[{{module}}]` `[{{size}}]`
+- [ ] {{task}} `[{{module}}]` `[{{size}}]`
+
+### Done
+
+- [x] {{completed_task}} `[{{module}}]`
+
+---
+
+## Task Format
+
+Each task should include:
+
+- **Description**: What needs to be done
+- **Module**: Which Project Graph module this belongs to
+- **Size**: S (< 1hr), M (1-4hr), L (4-8hr), XL (> 8hr)
+- **Dependencies**: What must be done first
+- **Acceptance criteria**: How to know it's done
+- **Skills needed**: Which skills the AI should load
+
+### Example Task
+
+```
+- [ ] Implement appointment calendar API [appointments] [L]
+  Dependencies: auth module, database schema
+  Acceptance: CRUD endpoints for appointments, tests passing
+  Skills: node, typescript, postgres, testing
+```
+
+## Backlog
+<!-- Tasks not yet assigned to a sprint -->
+- [ ] {{backlog_task_1}}
+- [ ] {{backlog_task_2}}

package/catalog/skills/generators/templates/UI.md

@@ -0,0 +1,73 @@
+# {{Project Name}} - UI/UX Specification
+
+## Design System
+
+### Colors
+
+| Token | Value | Usage |
+| --- | --- | --- |
+| `--color-primary` | {{hex}} | Primary actions, links |
+| `--color-secondary` | {{hex}} | Secondary elements |
+| `--color-background` | {{hex}} | Page background |
+| `--color-surface` | {{hex}} | Card/panel backgrounds |
+| `--color-text` | {{hex}} | Body text |
+| `--color-text-muted` | {{hex}} | Secondary text |
+| `--color-error` | {{hex}} | Error states |
+| `--color-success` | {{hex}} | Success states |
+
+### Typography
+
+| Level | Font | Size | Weight | Line Height |
+| --- | --- | --- | --- | --- |
+| H1 | {{font}} | {{size}} | {{weight}} | {{lh}} |
+| H2 | {{font}} | {{size}} | {{weight}} | {{lh}} |
+| Body | {{font}} | {{size}} | {{weight}} | {{lh}} |
+| Caption | {{font}} | {{size}} | {{weight}} | {{lh}} |
+
+### Spacing Scale
+
+`4px, 8px, 12px, 16px, 24px, 32px, 48px, 64px`
+
+### Border Radius
+
+| Token | Value | Usage |
+| --- | --- | --- |
+| `--radius-sm` | 4px | Inputs, small elements |
+| `--radius-md` | 8px | Cards, panels |
+| `--radius-lg` | 16px | Modals, hero sections |
+| `--radius-full` | 9999px | Pills, avatars |
+
+## Pages
+
+### {{Page Name}}
+
+- **Route:** `{{route}}`
+- **Purpose:** {{what this page does}}
+- **Components:** {{list of components}}
+- **States:** default, loading, empty, error
+
+## Component Library
+<!-- List of reusable components -->
+
+| Component | Props | Variants |
+| --- | --- | --- |
+| Button | `variant, size, disabled` | primary, secondary, ghost |
+| Input | `type, label, error` | text, email, password |
+| Card | `title, actions` | default, elevated |
+
+## Responsive Breakpoints
+
+| Name | Width | Layout |
+| --- | --- | --- |
+| Mobile | < 640px | Single column |
+| Tablet | 640-1024px | Two columns |
+| Desktop | > 1024px | Full layout |
+
+## Anti-Patterns (avoid these)
+
+- No gray text on colored backgrounds
+- No pure black - always tint with brand color
+- No bounce/elastic easing - use ease-out
+- No cards nested inside cards
+- No generic color palettes (plain red, blue, green)
+- No default browser fonts - use curated typography