contextos-agents 1.5.0

package/.agents/generated/gemini/skills/gemini-precision/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: gemini-precision
+description: >
+  High-precision engineering and execution guardrails optimized for Google Gemini models. Enforces zero-assumption file inspection, complete non-lazy implementations, surgical blast-radius containment, and mandatory proof-of-work execution.
+---
+# gemini-precision
+
+## Overview
+
+High-precision operational standard designed specifically to harness the high speed and expansive context window of Google Gemini models while eliminating common LLM failure modes: hasty assumptions, partial code placeholders (`// ...`), unverified assertions, and scope creep.
+
+## When to Use
+
+Activate whenever:
+
+- Executing non-trivial code modifications, refactoring, bug fixes, or architecture design.
+- The user requires maximum rigor, reliability, and precision from Gemini.
+- Handling complex multi-file changes where accidental side-effects must be zero.
+
+## Rules & Patterns
+
+### 1. The Read-Before-Write Invariant (Zero Assumptions)
+
+**Never write code based on assumptions about the codebase.**
+
+- Before modifying a function or creating an integration, **always inspect the actual files** using `view_file` or `grep_search`.
+- Check the exact runtime, framework version, and installed dependencies (e.g. React 19 vs 18, Next.js 15 vs 14, Tailwind v4 vs v3, Zod vs Joi) in `package.json` or config files before generating code.
+- Verify imported symbol names and parameter signatures directly from source files.
+
+### 2. The Zero-Placeholder Invariant (Complete Code Only)
+
+**Never produce lazy, incomplete, or stubbed output.**
+
+- ❌ **Forbidden**:
+  - `// TODO: implement logic here`
+  - `// ... rest of existing code ...`
+  - `// ... existing imports ...`
+  - Mock stub returns when real integration is required
+- ✅ **Mandatory**:
+  - Provide **100% complete, fully-implemented, compilable, and drop-in ready** code.
+  - When replacing a block of code, include all necessary imports, type definitions, and edge-case handling.
+
+### 3. The Proof-of-Work Invariant (Verification Before Completion)
+
+**Never claim a task is complete without tool-verified evidence.**
+
+- When modifying code or configuration:
+  1. Run the project validator or compiler (`node .agents/ctx.js validate`, `tsc --noEmit`, etc.).
+  2. Run unit and integration tests (`npm test`, `pytest`, etc.).
+  3. Run linter and formatting checks (`npm run lint:md`, `eslint`, etc.).
+- If a test or validation fails, do not guess: read the exact error trace, fix the root cause, and re-run until green.
+
+### 4. Surgical Blast Radius Containment
+
+**Modify ONLY what is strictly necessary.**
+
+- Keep edits isolated to the exact lines, functions, and files specified in the plan.
+- Do not reformat, reorder, or alter indentation of unrelated code blocks.
+- Preserve existing comments, docstrings, and project conventions unless explicitly asked to change them.
+
+### 5. Ponytail Minimalism (YAGNI)
+
+- Prioritize native platform APIs (standard library, browser built-ins) over new npm/pip packages.
+- Follow the "Rule of Three": inline on first use, duplicate cleanly on second, abstract only on third.
+- Keep solutions obvious to a mid-level developer without requiring multi-layered wrapper classes.
+
+### 6. Targeted Tool-Specific Modifications
+
+**Prevent accidental code loss during file updates.**
+
+- For existing files requiring localized updates (< 50% change), always prefer surgical targeted replacement chunks over destructive full-file rewrites.
+- Never discard unrelated file sections, existing comments, or helper utilities.
+
+### 7. Persistent Context & Plan Tracking
+
+**Prevent context drift during multi-step tasks.**
+
+- When an operation requires more than 3 sequential steps, write and maintain a persistent plan or checklist on disk.
+- Never rely exclusively on volatile conversational memory for tracking complex multi-file refactorings.
+
+### 8. Progressive Step Narration (Transparent Pair Programming)
+
+**Eliminate the "black box" by narrating technical decisions.**
+
+- Avoid executing long, silent chains of tool calls without user visibility.
+- Provide a concise 1–2 sentence transparent status update before key operations:
+  - State what was inspected or verified from the code.
+  - State the architectural decision made and the immediate next action.
+- Keep narration crisp and actionable without excessive verbosity.
+
+---
+
+## Code Examples
+
+### Bad (Lazy Model Output) vs Good (Precision Model Output)
+
+**❌ Bad (Lazy AI Output)**:
+
+```javascript
+// user.service.js
+export async function updateUser(id, data) {
+  // ... existing auth check ...
+  // TODO: validate data with zod
+  return await db.user.update({ where: { id }, data });
+}
+```
+
+**✅ Good (Gemini Precision Output)**:
+
+```javascript
+// user.service.js
+import { z } from 'zod';
+import { db } from '../lib/db.js';
+import { ValidationError, UnauthorizedError } from '../errors/index.js';
+
+const UpdateUserSchema = z.object({
+  name: z.string().min(1).max(100).optional(),
+  email: z.string().email().optional(),
+}).strict();
+
+export async function updateUser(id, data, session) {
+  if (!session?.userId || session.userId !== id) {
+    throw new UnauthorizedError('Access denied: cannot update another user');
+  }
+
+  const parsed = UpdateUserSchema.safeParse(data);
+  if (!parsed.success) {
+    throw new ValidationError('Invalid update payload', parsed.error.format());
+  }
+
+  return await db.user.update({
+    where: { id },
+    data: parsed.data,
+    select: { id: true, name: true, email: true, updatedAt: true }
+  });
+}
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Inspected active codebase files before writing code.
+- [ ] Delivered 100% complete code with zero `// TODO` or `// ...` placeholders.
+- [ ] Ran automated tests and validation with green status.
+- [ ] Confined changes to the minimal required blast radius.
+- [ ] Preserved existing code via targeted edits rather than full-file overwrites.
+- [ ] Persisted multi-step task state and milestones to disk.
+- [ ] Narrated progress with concise, transparent step-by-step updates.
+- [ ] Reported final status with verifiable evidence.
+
+---
+
+## Common Mistakes
+
+- **Assuming API contracts**: Guessing function parameters without opening the file.
+- **Premature completion**: Declaring "fixed" without running the test suite.
+- **Uncontrolled refactoring**: Rewriting adjacent components while fixing a 1-line bug.
+
+---
+
+## Integration Notes
+
+- Pairs with `engineering-workflow` to enforce the 6-phase pipeline.
+- Enforces the 7-rung ladder of `ponytail-mindset`.
+- Acts as the baseline behavioral guardrail across all Gemini and Antigravity operations.
+

package/.agents/generated/gemini/skills/generators/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: generators
+description: >
+  Generates complete project documentation (PRD, Architecture, Database, API, UI, Roadmap, Tasks) from ideas and templates with incremental update support.
+---
+# 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.
+
+## Commands
+
+### `ctx init`
+
+Full project initialization. From one user prompt, generate ALL documents:
+
+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
+   - `docs/UI.md` — UI/UX Specification
+   - `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 config via Adapters skill
+
+### `ctx update`
+
+Incremental update. When requirements change:
+
+1. Identify which documents are affected
+2. Update only affected documents
+3. Show diff of changes
+4. Ask user to confirm
+5. Update Project Graph if structure changed
+
+### `ctx plan`
+
+Generate development plan from existing PRD:
+
+1. Read `docs/PRD.md`
+2. Break into modules (Project Graph)
+3. Break modules into features
+4. Break features into tasks
+5. Estimate complexity (S/M/L/XL)
+6. Output to `docs/TASKS.md`
+
+## 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.
+
+
+<!-- Source: EXAMPLES.md -->
+
+# generators Examples — Anti-patterns vs ContextOS Standard
+
+## Example 1: Technical Documentation Generation
+
+### Anti-pattern: Scaffolding from Scratch Without Templates
+
+```text
+Agent drafts a 2-paragraph "architecture overview" missing databases, security, and hosting models.
+```
+
+### Best practice: ContextOS Standard (ctx init Template Generation)
+
+```text
+Generates complete engineering suite:
+- PRD.md (User personas, in-scope, out-of-scope, acceptance criteria)
+- ARCHITECTURE.md (C4 model, data flow, scaling boundaries)
+- DATABASE.md (ERD, indexing strategy, migration plans)
+- API.md (OpenAPI 3.1 endpoints, error codes, authentication)
+```
+
+<!-- Source: TROUBLESHOOTING.md -->
+
+# 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/.agents/generated/gemini/skills/graphify/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: graphify
+description: >
+  Codebase knowledge graph generator via Tree-sitter AST parsing and semantic indexing. Minimizes token consumption and maps dependency blast radius.
+---
+# graphify
+
+## Overview
+
+**Graphify** is a codebase mapping and context optimization engine. Instead of feeding raw directory trees or entire source files into an agent's context window, Graphify leverages local **Tree-sitter** AST parsing to construct a deterministic, queryable knowledge graph (`graph.json`, `GRAPH_REPORT.md`, `graph.html`).
+
+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.
+
+
+<!-- Source: EXAMPLES.md -->
+
+# 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
+```