contextos-agents 1.5.0

package/.agents/core/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/.agents/core/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/.agents/core/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/.agents/core/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/.agents/core/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/.agents/core/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/.agents/core/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/.agents/core/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/.agents/core/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

package/.agents/core/skills/graphify/EXAMPLES.md

@@ -0,0 +1,73 @@
+# Graphify Examples — Anti-patterns vs ContextOS Standard
+
+## Example 1: Codebase Exploration & Architecture Mapping
+
+### Anti-pattern: Context Window Flooding (Dumping source directories into prompt)
+
+```bash
+# BAD: Reading 150 TypeScript files into context to understand system architecture.
+# Burns 200k+ tokens, causes model hallucinations, and loses attention span.
+cat src/**/*.ts | llm "explain the architecture and component connections"
+```
+
+### Best practice: ContextOS Standard (Deterministic Tree-sitter AST Graph)
+
+```bash
+# GOOD: Generate queryable AST knowledge graph and compact architecture summary
+graphify run ./src --output .graphify/
+
+# Inspect high-level architecture and god nodes with minimal tokens (<2k tokens)
+cat .graphify/GRAPH_REPORT.md
+```
+
+---
+
+## Example 2: Refactoring Blast-Radius Analysis
+
+### Anti-pattern: String Grep Guesswork
+
+```bash
+# BAD: Grepping for common symbol names returns hundreds of false positives (comments, logs, unrelated types)
+grep -rn "PaymentService" src/
+```
+
+### Best practice: ContextOS Standard (Inbound Dependency Traversal via graph.json)
+
+```javascript
+// GOOD: Precise AST-level callers extracted directly from knowledge graph edges
+const fs = require('fs');
+const graph = JSON.parse(fs.readFileSync('.graphify/graph.json', 'utf8'));
+
+const targetNode = 'PaymentService';
+const dependents = graph.edges
+  .filter(edge => edge.target === targetNode && edge.type === 'imports')
+  .map(edge => edge.source);
+
+console.log(`Modules directly broken by modifying ${targetNode}:`, dependents);
+```
+
+---
+
+## Example 3: Keeping Graph Fresh in CI / Pre-commit
+
+### Anti-pattern: Relying on Outdated Graphs
+
+```bash
+# BAD: Developing against a graph generated two months ago.
+# Dependencies drift, leading to false safety assumptions.
+```
+
+### Best practice: ContextOS Standard (Git Hook & Automated Watch)
+
+```bash
+# Option A: Active development in watch mode
+graphify watch ./src --output .graphify/
+
+# Option B: Pre-commit hook to verify fresh GRAPH_REPORT.md
+#!/bin/sh
+# .git/hooks/pre-commit
+if command -v graphify >/dev/null 2>&1; then
+  graphify run ./src --report-only
+  git add GRAPH_REPORT.md
+fi
+```