contextos-agents 2.1.0 → 2.2.0

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

package/catalog/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
+```

package/catalog/skills/graphify/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: graphify
+description: >
+  Codebase knowledge graph generator and architecture mapping guide.
+  Eliminates context window burn, enables precise dependency mapping, and identifies architectural god nodes.
+---
+
+# graphify
+
+## Overview
+
+**Graphify** is an instruction-only codebase mapping and context optimization guide. Instead of feeding raw directory trees or entire source files into an agent's context window, Graphify instructs agents on how to construct a deterministic, queryable knowledge graph (`graph.json`, `GRAPH_REPORT.md`, `graph.html`) using external companion analyzers (such as the TypeScript AST analyzer in `contextos-mcp` or the external `graphifyy` CLI), keeping the core package 100% zero-dependency without bundled native Tree-sitter binaries.
+
+This skill instructs agents how to build, query, and maintain codebase graphs to navigate complex architectures with near-zero token overhead.
+
+## When to Use
+
+Activate whenever:
+
+- Working in large repositories (10k+ LOC) where full-file reads cause context overflow.
+- Performing cross-module refactorings and needing to determine exact dependency **blast radius**.
+- Onboarding onto an unfamiliar codebase or mapping legacy service boundaries.
+- The user asks to "map the codebase", "show dependency graph", "find central components", or "run graphify".
+- Working alongside `context-manager` to supply an automated `PROJECT_GRAPH.md` / `graph.json`.
+
+## Rules & Patterns
+
+### 1. The Graph-First Navigation Protocol
+
+Before opening and reading arbitrary source files in a large project:
+
+1. **Check for Existing Artifacts**:
+   - Inspect if `graph.json` or `GRAPH_REPORT.md` exists in the project root or `.graphify/`.
+   - If present, query `graph.json` or read `GRAPH_REPORT.md` first to locate target modules.
+2. **Deterministic CLI Execution**:
+   - If missing or stale, generate the graph using the Python package (`pip install graphifyy`):
+
+     ```bash
+     graphify run .
+     ```
+
+   - For live development sessions, run in watch mode:
+
+     ```bash
+     graphify watch .
+     ```
+
+3. **Inspect God Nodes**:
+   - Always check the "God Nodes" section of `GRAPH_REPORT.md`. These represent high-centrality modules (e.g., core configs, base models, central dispatchers). Changes to god nodes have the highest blast radius.
+
+### 2. Context Safety Rules
+
+- **Never load `graph.html` into agent context**: `graph.html` is an interactive visualization for humans in the browser; reading it burns tokens needlessly.
+- **Selective JSON Querying**: Do not dump the entire `graph.json` into prompt context if it exceeds 50KB. Use targeted grep/jq queries to extract specific node neighbors.
+- **Git Hygiene**: Add `graph.html` and `.graphify/cache` to `.gitignore`. Keep `GRAPH_REPORT.md` committed only if the team uses it as shared documentation.
+
+### 3. Blast Radius Verification
+
+When modifying a function, class, or interface:
+
+1. Locate the symbol's node in `graph.json`.
+2. Extract all inbound edges (`dependents` / `callers`).
+3. Formulate the verification plan specifically around those dependent call sites.
+
+---
+
+## Code Examples
+
+### Installing and Running Graphify
+
+```bash
+# Install graphify CLI (package name is graphifyy on PyPI)
+pip install graphifyy
+
+# Generate knowledge graph and markdown architectural report
+graphify run ./src --output .graphify/
+
+# View interactive visualization locally
+open .graphify/graph.html
+```
+
+### Querying Node Dependencies via Shell
+
+```bash
+# Find dependents of a critical module in graph.json without loading entire file
+node -e "
+const g = require('./.graphify/graph.json');
+const target = 'UserService';
+const inbound = g.edges.filter(e => e.target === target).map(e => e.source);
+console.log('Modules dependent on ' + target + ':', inbound);
+"
+```
+
+### Git Pre-Commit Hook Integration
+
+```bash
+#!/bin/sh
+# .git/hooks/pre-commit: ensure GRAPH_REPORT.md remains fresh
+if command -v graphify >/dev/null 2>&1; then
+  graphify run . --report-only
+  git add GRAPH_REPORT.md
+fi
+```
+
+---
+
+## Validation Checklist
+
+- [ ] `graph.json` and `GRAPH_REPORT.md` are generated without syntax errors.
+- [ ] Central "God Nodes" are identified and accounted for in the implementation plan.
+- [ ] No heavy visualization artifacts (`graph.html`, raw SVG dumps) are ingested into agent prompt context.
+- [ ] Inbound dependencies (callers) are checked before modifying exported signatures.
+- [ ] `.gitignore` properly excludes local graph caches and visualization outputs.
+
+---
+
+## Common Mistakes
+
+- **Context Window Flooding**: Ingesting the complete `graph.json` of a 500k LOC repository into agent context instead of slicing target subgraphs.
+- **Stale Graph Fallacy**: Assuming `graph.json` is up to date after heavy code refactorings without re-running `graphify run` or using `--watch`.
+- **Ignoring Semantic Non-Code Files**: Neglecting SQL migrations, OpenAPI specs, and docker configs during graph extraction.
+- **Mistaking Package Name**: Trying to install `pip install graphify` instead of the official PyPI package `graphifyy`.
+
+---
+
+## Integration Notes
+
+- **Synergy with `context-manager`**: Graphify serves as the automated backend engine for `context-manager`. Instead of manually maintaining `docs/PROJECT_GRAPH.md`, run Graphify to keep `graph.json` current.
+- **Synergy with `system-design`**: Use `GRAPH_REPORT.md` to ground architectural proposals in actual codebase topology.
+- **Synergy with `architecture-diagrams`**: The nodes and edges extracted in `graph.json` can be directly mapped into animated SVG C4 architecture diagrams.

package/catalog/skills/graphify/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/graphify/skill.yaml

@@ -0,0 +1,13 @@
+schemaVersion: 2
+name: graphify
+category: architecture
+type: instruction-only
+description: Codebase knowledge graph generator and architecture mapping guide. Instructs agents on AST dependency extraction and blast radius analysis.
+version: 1.0.0
+optional:
+  - context-manager
+  - system-design
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - VALIDATION.json

package/catalog/skills/impeccable-design/EXAMPLES.md

@@ -0,0 +1,26 @@
+# impeccable-design Examples - Anti-patterns vs ContextOS Standard
+
+## Example 1: Dark Mode Surfaces & Elevation
+
+### Anti-pattern: Pure Black with Flat Cards
+
+```css
+/* BAD: Pure #000000 background with harsh pure white borders and flat cards */
+body { background-color: #000000; color: #ffffff; }
+.card { background-color: #111111; border: 1px solid #ffffff; }
+```
+
+### Best practice: ContextOS Standard (Atmospheric Depth & Tinted Surfaces)
+
+```css
+/* GOOD: Tinted dark background with layered elevation surfaces and subtle border */
+body {
+  background-color: #0B0D13; /* Tinted with subtle deep blue */
+  color: #E2E8F0;
+}
+.surface-1 {
+  background-color: #111522;
+  border: 1px solid rgba(255, 255, 255, 0.08);
+  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.25);
+}
+```