contextos-agents 1.6.0 → 1.7.0

package/.agents/AGENTS.md

@@ -22,6 +22,10 @@ State your answers explicitly:
 Skills loaded: react, typescript, ui-ux-pro, ponytail-mindset
 ```
 
+> **Anti-Spam Invariant**:
+> Declare `[DOMAIN: ...] [PHASE: ...] [ROLE: ...]` **strictly once** at the beginning of a user task or when transitioning between major phases (`DEFINE → PLAN → BUILD → VERIFY → REVIEW → SHIP`).
+> **NEVER** prefix intermediate tool calls, file reads, grep searches, or step updates with this header.
+
 ---
 
 ## Skill Architecture (Context Efficiency)
@@ -372,6 +376,7 @@ These rules apply regardless of which skills are loaded:
 
 ### Engineering
 - No code before spec + plan are approved in interactive development (proceed directly to BUILD when standalone/benchmark code is requested)
+- **Fast-Track Exception**: For routine maintenance, operational tasks (git commands, version bump, lint fix, typo, single-line config tweaks, diagnostics, and direct questions), proceed directly without blocking on full `/spec` and `/plan` approval rituals.
 - Blast radius limited to files in current task's plan
 - One atomic commit per task
 

package/.agents/adapters/aider/export.js

@@ -92,12 +92,14 @@ function run() {
     `\n---\n\n## Project Rules\n\n` +
     `### Step 0 — Identify Before Acting\n\n` +
     `Before writing a single line of code or plan, state:\n` +
-    `\`\`\`\n1. WHAT DOMAIN?   → Frontend / Backend / Architecture / Full-Stack / DevOps\n2. WHAT PHASE?    → Define / Plan / Build / Verify / Review / Ship\n3. WHAT ROLE?     → Declare specialist role for this phase\n\`\`\`\n\n` +
+    `\`\`\`\n1. WHAT DOMAIN?   → Frontend / Backend / Architecture / Full-Stack / DevOps\n2. WHAT PHASE?    → Define / Plan / Build / Verify / Review / Ship\n3. WHAT ROLE?     → Declare specialist role for this phase\n\`\`\`\n` +
+    `> **Anti-Spam Invariant**: Declare this strictly once at the start of a task or phase. Never repeat before intermediate tool calls or step updates.\n\n` +
     `### Non-Negotiable Rules\n\n` +
     `- **Zero-Assumption Investigation**: Never guess file paths or signatures. Inspect before modifying.\n` +
     `- **Zero-Placeholder Production Code**: Never emit lazy stubs, \`// TODO\`, or partial code.\n` +
     `- **Mandatory Proof-of-Work Verification**: Always run tests and validators before claiming completion.\n` +
-    `- **Surgical Blast Radius**: Modify only files strictly within scope.\n`
+    `- **Surgical Blast Radius**: Modify only files strictly within scope.\n` +
+    `- **Fast-Track Exception**: Routine maintenance, git commands, version bumps, typo fixes, and diagnostics skip spec/plan ceremonies.\n`
   );
 
   // Skills Router Table

package/.agents/adapters/copilot/export.js

@@ -59,12 +59,14 @@ function run() {
   lines.push(`## Project Rules\n\n`);
   lines.push(`### Step 0 — Identify Before Acting\n\n`);
   lines.push(`Before writing a single line of code or plan, state:\n`);
-  lines.push(`\`\`\`\n1. WHAT DOMAIN?   → Frontend / Backend / Architecture / Full-Stack / DevOps\n2. WHAT PHASE?    → Define / Plan / Build / Verify / Review / Ship\n3. WHAT ROLE?     → Declare specialist role for this phase\n\`\`\`\n\n`);
+  lines.push(`\`\`\`\n1. WHAT DOMAIN?   → Frontend / Backend / Architecture / Full-Stack / DevOps\n2. WHAT PHASE?    → Define / Plan / Build / Verify / Review / Ship\n3. WHAT ROLE?     → Declare specialist role for this phase\n\`\`\`\n`);
+  lines.push(`> **Anti-Spam Invariant**: Declare this strictly once at the start of a task or phase. Never repeat before intermediate tool calls or step updates.\n\n`);
   lines.push(`### Non-Negotiable Rules\n\n`);
   lines.push(`- **Zero-Assumption Investigation**: Never guess file paths or signatures. Inspect before modifying.\n`);
   lines.push(`- **Zero-Placeholder Production Code**: Never emit lazy stubs, \`// TODO\`, or partial code.\n`);
   lines.push(`- **Mandatory Proof-of-Work Verification**: Always run tests and validators before claiming completion.\n`);
-  lines.push(`- **Surgical Blast Radius**: Modify only files strictly within scope.\n\n`);
+  lines.push(`- **Surgical Blast Radius**: Modify only files strictly within scope.\n`);
+  lines.push(`- **Fast-Track Exception**: Routine maintenance, git commands, version bumps, typo fixes, and diagnostics skip spec/plan ceremonies.\n\n`);
   lines.push(`---\n`);
 
   // ── Skills ───────────────────────────────────────────────────────────────────

package/.agents/adapters/cursor/export.js

@@ -133,6 +133,12 @@ ${body}
 function run() {
   console.log('Starting Cursor adapter export...');
 
+  const outputFile = path.join(process.cwd(), '.cursorrules');
+  const cursorRulesDir = path.join(process.cwd(), '.cursor', 'rules');
+  const agentsMdPath = fs.existsSync(path.join(process.cwd(), '.agents', 'AGENTS.md'))
+    ? path.join(process.cwd(), '.agents', 'AGENTS.md')
+    : AGENTS_MD_PATH;
+
   const sections = [];
 
   // ── Header ──────────────────────────────────────────────────────────────────
@@ -146,14 +152,14 @@ function run() {
   );
 
   // Prepare .cursor/rules directory
-  fs.mkdirSync(CURSOR_RULES_DIR, { recursive: true });
+  fs.mkdirSync(cursorRulesDir, { recursive: true });
 
   let count = 0;
   let mdcCount = 0;
 
   // Write 00-project-rules.mdc
-  if (fs.existsSync(AGENTS_MD_PATH)) {
-    const agentsMd = fs.readFileSync(AGENTS_MD_PATH, 'utf8');
+  if (fs.existsSync(agentsMdPath)) {
+    const agentsMd = fs.readFileSync(agentsMdPath, 'utf8');
     const projectMdc = `---
 description: "ContextOS core project rules and role orchestration"
 globs: ""
@@ -164,7 +170,7 @@ alwaysApply: true
 
 ${agentsMd}
 `;
-    fs.writeFileSync(path.join(CURSOR_RULES_DIR, '00-project-rules.mdc'), projectMdc);
+    fs.writeFileSync(path.join(cursorRulesDir, '00-project-rules.mdc'), projectMdc);
     mdcCount++;
   }
 
@@ -185,23 +191,53 @@ ${agentsMd}
     if (mdc) {
       const mdcFileName = `${mdc.skillName}.mdc`;
       activeMdcFiles.add(mdcFileName);
-      fs.writeFileSync(path.join(CURSOR_RULES_DIR, mdcFileName), mdc.mdcContent);
+      fs.writeFileSync(path.join(cursorRulesDir, mdcFileName), mdc.mdcContent);
       mdcCount++;
     }
   }
 
-  // Clean up stale .mdc rules from uninstalled skills/plugins
-  if (fs.existsSync(CURSOR_RULES_DIR)) {
-    for (const file of fs.readdirSync(CURSOR_RULES_DIR)) {
+  // Clean up stale .mdc rules from uninstalled skills/plugins safely (provenance-verified only)
+  if (fs.existsSync(cursorRulesDir)) {
+    const lockfilePath = path.join(process.cwd(), '.agents', 'contextos.lock.json');
+    let lockData = null;
+    try {
+      if (fs.existsSync(lockfilePath)) {
+        lockData = JSON.parse(fs.readFileSync(lockfilePath, 'utf8'));
+      }
+    } catch {}
+
+    for (const file of fs.readdirSync(cursorRulesDir)) {
       if (file.endsWith('.mdc') && !activeMdcFiles.has(file)) {
-        fs.unlinkSync(path.join(CURSOR_RULES_DIR, file));
+        const fullFilePath = path.join(cursorRulesDir, file);
+        const relPath = path.relative(process.cwd(), fullFilePath).replace(/\\/g, '/');
+
+        // Deletion permitted ONLY if recorded in lockfile OR content carries explicit ContextOS provenance
+        const isManagedInLock = Boolean(lockData?.managedFiles?.[relPath]?.managed);
+        let hasContextosMarker = false;
+        try {
+          const content = fs.readFileSync(fullFilePath, 'utf8');
+          hasContextosMarker =
+            content.includes('<!-- Auto-generated by: node .agents/ctx.js export cursor -->') ||
+            content.includes('ContextOS rules for') ||
+            content.includes('ContextOS — Project Operating System Rules');
+        } catch {}
+
+        if (isManagedInLock || hasContextosMarker) {
+          fs.unlinkSync(fullFilePath);
+          if (lockData?.managedFiles?.[relPath]) {
+            delete lockData.managedFiles[relPath];
+            try {
+              fs.writeFileSync(lockfilePath, JSON.stringify(lockData, null, 2) + '\n', 'utf8');
+            } catch {}
+          }
+        }
       }
     }
   }
 
-  fs.writeFileSync(OUTPUT_FILE, sections.join('\n'));
-  console.log(`Generated .cursorrules (${count} skills) → ${OUTPUT_FILE}`);
-  console.log(`Generated .cursor/rules/*.mdc (${mdcCount} rules) → ${CURSOR_RULES_DIR}`);
+  fs.writeFileSync(outputFile, sections.join('\n'));
+  console.log(`Generated .cursorrules (${count} skills) → ${outputFile}`);
+  console.log(`Generated .cursor/rules/*.mdc (${mdcCount} rules) → ${cursorRulesDir}`);
 }
 
 module.exports = { run };

package/.agents/adapters/zed/export.js

@@ -46,15 +46,22 @@ function buildSkillSection(skillDir) {
     skillName,
     title,
     section: `\n### Skill: ${title}\n${descLine}${promptRef}`,
-    prompt: `# ContextOS — ${title}\n\n${descLine}\n${body}\n`,
+    prompt: `<!-- Auto-generated by: node .agents/ctx.js export zed -->\n# ContextOS — ${title}\n\n${descLine}\n${body}\n`,
   };
 }
 
 function run() {
   console.log('Starting Zed IDE adapter export...');
 
-  fs.mkdirSync(ZED_DIR, { recursive: true });
-  fs.mkdirSync(PROMPTS_DIR, { recursive: true });
+  const zedDir = path.join(process.cwd(), '.zed');
+  const rulesFile = path.join(zedDir, 'rules.md');
+  const promptsDir = path.join(zedDir, 'prompts');
+  const agentsMdPath = fs.existsSync(path.join(process.cwd(), '.agents', 'AGENTS.md'))
+    ? path.join(process.cwd(), '.agents', 'AGENTS.md')
+    : AGENTS_MD_PATH;
+
+  fs.mkdirSync(zedDir, { recursive: true });
+  fs.mkdirSync(promptsDir, { recursive: true });
 
   const lines = [];
 
@@ -66,12 +73,15 @@ function run() {
   );
 
   // ── Project Rules ────────────────────────────────────────────────────────────
-  if (fs.existsSync(AGENTS_MD_PATH)) {
-    const agentsMd = fs.readFileSync(AGENTS_MD_PATH, 'utf8');
+  if (fs.existsSync(agentsMdPath)) {
+    const agentsMd = fs.readFileSync(agentsMdPath, 'utf8');
     lines.push(`## Project Rules (AGENTS.md)\n\n${agentsMd}\n\n---\n`);
 
     // Also write a master prompt in .zed/prompts/contextos.md
-    fs.writeFileSync(path.join(PROMPTS_DIR, 'contextos.md'), `# ContextOS Master Prompt\n\n${agentsMd}\n`);
+    fs.writeFileSync(
+      path.join(promptsDir, 'contextos.md'),
+      `<!-- Auto-generated by: node .agents/ctx.js export zed -->\n# ContextOS Master Prompt\n\n${agentsMd}\n`
+    );
   }
 
   // ── Skills ───────────────────────────────────────────────────────────────────
@@ -88,24 +98,53 @@ function run() {
       lines.push(skillData.section);
       const promptFileName = `${skillData.skillName}.md`;
       activePromptFiles.add(promptFileName);
-      fs.writeFileSync(path.join(PROMPTS_DIR, promptFileName), skillData.prompt);
+      fs.writeFileSync(path.join(promptsDir, promptFileName), skillData.prompt);
       count++;
     }
   }
 
-  // Clean up stale prompts from uninstalled skills/plugins
-  if (fs.existsSync(PROMPTS_DIR)) {
-    for (const file of fs.readdirSync(PROMPTS_DIR)) {
+  // Clean up stale prompts from uninstalled skills/plugins safely (provenance-verified only)
+  if (fs.existsSync(promptsDir)) {
+    const lockfilePath = path.join(process.cwd(), '.agents', 'contextos.lock.json');
+    let lockData = null;
+    try {
+      if (fs.existsSync(lockfilePath)) {
+        lockData = JSON.parse(fs.readFileSync(lockfilePath, 'utf8'));
+      }
+    } catch {}
+
+    for (const file of fs.readdirSync(promptsDir)) {
       if (file.endsWith('.md') && !activePromptFiles.has(file)) {
-        fs.unlinkSync(path.join(PROMPTS_DIR, file));
+        const fullFilePath = path.join(promptsDir, file);
+        const relPath = path.relative(process.cwd(), fullFilePath).replace(/\\/g, '/');
+
+        const isManagedInLock = Boolean(lockData?.managedFiles?.[relPath]?.managed);
+        let hasContextosMarker = false;
+        try {
+          const content = fs.readFileSync(fullFilePath, 'utf8');
+          hasContextosMarker =
+            content.includes('<!-- Auto-generated by: node .agents/ctx.js export zed -->') ||
+            content.includes('# ContextOS —') ||
+            content.includes('# ContextOS Master Prompt');
+        } catch {}
+
+        if (isManagedInLock || hasContextosMarker) {
+          fs.unlinkSync(fullFilePath);
+          if (lockData?.managedFiles?.[relPath]) {
+            delete lockData.managedFiles[relPath];
+            try {
+              fs.writeFileSync(lockfilePath, JSON.stringify(lockData, null, 2) + '\n', 'utf8');
+            } catch {}
+          }
+        }
       }
     }
   }
 
   // Write master .zed/rules.md
-  fs.writeFileSync(RULES_FILE, lines.join(''));
-  console.log(`Generated .zed/rules.md (${count} skills) → ${RULES_FILE}`);
-  console.log(`Generated .zed/prompts/*.md (${count} prompts) → ${PROMPTS_DIR}`);
+  fs.writeFileSync(rulesFile, lines.join(''));
+  console.log(`Generated .zed/rules.md (${count} skills) → ${rulesFile}`);
+  console.log(`Generated .zed/prompts/*.md (${count} prompts) → ${promptsDir}`);
 }
 
 module.exports = { run };

package/.agents/core/profiles/mvp.yaml

@@ -25,6 +25,7 @@ prefer_skills:
 exclude_skills:
   - ddd
   - microservices
+  - system-design
   - kubernetes
   - monitoring
   - cicd

package/.agents/core/skills/adapters/skill.yaml

@@ -1,4 +1,5 @@
 name: adapters
+type: compiler
 description: >
   Generates agent-specific configuration files from unified ContextOS format.
   Produces configs for Claude, Gemini, Copilot, Cursor, Aider, Continue, and Zed.
@@ -8,3 +9,8 @@ tags:
   - configuration
   - devops
 version: 1.0.0
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json

package/.agents/core/skills/architecture-diagrams/skill.yaml

@@ -1,4 +1,5 @@
 name: architecture-diagrams
+type: instruction-only
 description: Interactive, visual architecture and sequence diagrams as code. Generates beautiful, self-contained SVG/HTML diagrams with motion, clear component boundaries, and verifiable data flows.
 tags:
   - architecture
@@ -6,3 +7,6 @@ tags:
   - system-design
   - visualization
 version: 1.0.0
+resources:
+  - SKILL.md
+  - VALIDATION.json

package/.agents/core/skills/brutalist-design/skill.yaml

@@ -1,4 +1,5 @@
 name: brutalist-design
+type: instruction-only
 description: Raw mechanical interfaces fusing Swiss typographic print with military terminal aesthetics.
 tags:
   - ui
@@ -6,3 +7,6 @@ tags:
   - brutalist
   - typography
 version: 1.0.0
+resources:
+  - SKILL.md
+  - VALIDATION.json

package/.agents/core/skills/context-manager/references/context-rules.md

@@ -0,0 +1,59 @@
+# Context Loading Rules
+
+Guidelines and deterministic decision tables for selecting, prioritizing, and budgeting context during AI agent execution.
+
+## Task Type to Document Mapping
+
+| Task Type | Level 1 (Always) | Level 2 (If exists) | Level 3 (Per task) |
+| --- | --- | --- | --- |
+| **New project** | PRD, ROADMAP | ARCHITECTURE, DATABASE, API | UI, TASKS, all relevant skills |
+| **New feature** | PRD | ARCHITECTURE, API | PROJECT_GRAPH, relevant skills |
+| **Frontend** | — | ARCHITECTURE, API | UI, frontend skills |
+| **Backend** | — | ARCHITECTURE, DATABASE, API | backend skills |
+| **Database** | — | ARCHITECTURE, DATABASE | — |
+| **Bugfix** | — | — | PROJECT_GRAPH (affected module only) |
+| **Refactor** | — | ARCHITECTURE | PROJECT_GRAPH, affected skills |
+| **Review** | PRD | ARCHITECTURE | TASKS, all loaded skills |
+| **Deploy** | — | ARCHITECTURE | DEPLOYMENT, infrastructure skills |
+
+## Skill Category to Document Mapping
+
+| Skill Category | Required Documents | Optional Documents |
+| --- | --- | --- |
+| `frontend` | UI.md, API.md | ARCHITECTURE.md |
+| `backend` | API.md, DATABASE.md | ARCHITECTURE.md |
+| `design` | UI.md | PRD.md |
+| `architecture` | ARCHITECTURE.md, DATABASE.md | PRD.md, API.md |
+| `infrastructure` | ARCHITECTURE.md | — |
+| `security` | ARCHITECTURE.md, API.md | DATABASE.md |
+| `testing` | API.md | ARCHITECTURE.md |
+
+## Context Budgeting
+
+To prevent context window saturation and retain maximum LLM reasoning capacity, adhere strictly to the following 4-tier token budget:
+
+| Priority Level | Max Tokens | Contents |
+| --- | --- | --- |
+| 1 (Critical) | 2,000 | Current task description, active brief, and primary skill rules |
+| 2 (Important) | 3,000 | System architecture and API contracts for affected modules |
+| 3 (Context) | 2,000 | Architectural Decision Records (ADRs) and relevant graph nodes |
+| 4 (Background) | 1,000 | PRD summary and global project conventions |
+
+**Total target context budget: ~8,000 tokens per subtask.**
+
+### Degradation Strategy When Over Budget
+
+If accumulated context exceeds the 8,000 token limit:
+
+1. **Trim Level 1 documents** to high-level executive summaries.
+2. **Slice Level 2 documents** to extract only sections matching touched module signatures.
+3. **Preserve Level 3 skills** at full fidelity, as they contain non-negotiable operational instructions and validation guardrails.
+
+## Module-Based Filtering via Dependency Graph
+
+When `PROJECT_GRAPH.md` or `.graphify/graph.json` is present, traverse dependency edges to filter candidate documents:
+
+1. Identify the primary module for the task from the symbol/path mapping.
+2. Resolve immediate inbound and outbound dependencies (`dependencies` and `dependents`).
+3. Include documents solely for the identified module and its immediate dependencies.
+4. Exclude orthogonal domain documents (for example, omit database schemas during purely presentation-layer CSS/layout tasks).

package/.agents/core/skills/context-manager/skill.yaml

@@ -1,4 +1,5 @@
 name: context-manager
+type: instruction-only
 description: >
   Smart context selection engine. Analyzes the current task, consults the
   Project Graph, and returns only the documents and skills needed to prevent token overflow.
@@ -8,3 +9,9 @@ tags:
   - tokens
   - architecture
 version: 1.0.0
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json
+  - references/context-rules.md

package/.agents/core/skills/context-os/skill.yaml

@@ -1,4 +1,5 @@
 name: context-os
+type: compiler
 description: >
   AI Project Operating System context compiler that transforms user intent into
   minimal, relevant context for any AI agent across the full development lifecycle.
@@ -8,3 +9,13 @@ tags:
   - architecture
   - context
 version: 1.0.0
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json
+  - packs.yaml
+  - references/context-rules.md
+  - references/pipeline.md
+  - references/project-graph.md
+  - rules.yaml

package/.agents/core/skills/database/skill.yaml

@@ -2,6 +2,7 @@ name: database
 description: Database architecture, schema design, Prisma, Drizzle ORM, indexing strategies, migrations, and N+1 query resolution.
 version: 1.0.0
 category: backend
+type: instruction-only
 requires:
   - system-design
   - typescript
@@ -23,3 +24,8 @@ triggers:
     - "index"
     - "transaction"
     - "orm"
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json

package/.agents/core/skills/ddd/skill.yaml

@@ -1,6 +1,7 @@
 id: ddd
 name: Domain-Driven Design
 category: architecture
+type: instruction-only
 tags: [architecture, ddd, domain, bounded-context, aggregate]
 requires: []
 optional: [microservices, system-design]
@@ -8,3 +9,9 @@ conflicts: []
 weight: 6
 documents:
   - ddd.md
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json
+  - ddd.md

package/.agents/core/skills/decisions/skill.yaml

@@ -1,4 +1,5 @@
 name: decisions
+type: instruction-only
 description: >
   Architecture Decision Records (ADR) management. Creates, tracks, and queries
   architectural decisions so AI assistants understand why choices were made.
@@ -8,3 +9,8 @@ tags:
   - decisions
   - documentation
 version: 1.0.0
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json

package/.agents/core/skills/docker/skill.yaml

@@ -2,6 +2,7 @@ name: docker
 description: Docker containerization, multi-stage builds, non-root security, layer caching optimization, and docker-compose standards.
 version: 1.0.0
 category: devops
+type: instruction-only
 requires:
   - security
 triggers:
@@ -21,3 +22,8 @@ triggers:
     - "image"
     - "kubernetes"
     - "k8s"
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json

package/.agents/core/skills/engineering-workflow/SKILL.md

@@ -41,7 +41,7 @@ Inspired by [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills
 ```
 
 **IRON RULE**: In interactive development, no phase can be skipped and no code is written before `/plan` is approved.  
-**Direct Build Exception**: When the prompt/caller explicitly requests a standalone implementation, or declares `[PHASE: Build]`, execute the BUILD phase directly and deliver the complete, self-contained production code without conversational pauses.
+**Direct Build & Fast-Track Exception**: When the prompt/caller explicitly requests a standalone implementation, declares `[PHASE: Build]`, or requests routine operational/maintenance tasks (git operations, version bumps, typo fixes, small config tweaks, diagnostic checks), proceed directly to execution without conversational approval pauses.
 
 ---
 

package/.agents/core/skills/engineering-workflow/skill.yaml

@@ -1,4 +1,5 @@
 name: engineering-workflow
+type: instruction-only
 description: >
   Senior engineering workflow skill inspired by Addy Osmani's agent-skills.
   Enforces the full development lifecycle: spec → plan → build → test → review → ship.
@@ -11,3 +12,8 @@ tags:
   - review
 version: 1.0.0
 source: https://github.com/addyosmani/agent-skills
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json

package/.agents/core/skills/fastapi/skill.yaml

@@ -1,6 +1,7 @@
 id: fastapi
 name: FastAPI
 category: backend
+type: instruction-only
 tags: [backend, python, api, async, pydantic]
 requires: []
 optional: [postgres, redis, docker]
@@ -8,3 +9,9 @@ conflicts: [nestjs, express]
 weight: 8
 documents:
   - fastapi.md
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json
+  - fastapi.md

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

@@ -90,6 +90,10 @@ Activate whenever:
   - 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.
+- **Zero-Spam Constraint**:
+  - ❌ **Forbidden**: Starting every intermediate step, tool call, or status update with domain/phase/role tags (e.g. `[DOMAIN: ...] [PHASE: ...] [ROLE: ...]`).
+  - ✅ **Mandatory**: Declare role and phase strictly once at the start of a phase. Intermediate step updates must be clean, natural language sentences describing technical actions directly.
+  - Do not narrate routine micro-inspections (single line reads or basic greps). Announce only meaningful task phases and decisions.
 
 ---
 

package/.agents/core/skills/gemini-precision/skill.yaml

@@ -1,4 +1,5 @@
 name: gemini-precision
+type: instruction-only
 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.
 tags:
   - gemini
@@ -7,3 +8,6 @@ tags:
   - workflow
   - antigravity
 version: 1.0.0
+resources:
+  - SKILL.md
+  - VALIDATION.json

package/.agents/core/skills/generators/skill.yaml

@@ -1,4 +1,5 @@
 name: generators
+type: compiler
 description: >
   Generates complete project documentation (PRD, Architecture, Database, API, UI,
   Roadmap, Tasks) from ideas and templates with incremental update support.
@@ -8,3 +9,17 @@ tags:
   - architecture
   - templates
 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/.agents/core/skills/graphify/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: graphify
 description: >
-  Transforms entire codebases into structured knowledge graphs via Tree-sitter AST parsing.
+  Codebase knowledge graph generator and architecture mapping guide.
   Eliminates context window burn, enables precise dependency mapping, and identifies architectural god nodes.
 ---
 
@@ -9,7 +9,7 @@ description: >
 
 ## 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`).
+**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.
 

package/.agents/core/skills/graphify/skill.yaml

@@ -1,5 +1,6 @@
 name: graphify
-description: Codebase knowledge graph generator via Tree-sitter AST parsing and semantic indexing. Minimizes token consumption and maps dependency blast radius.
+type: instruction-only
+description: Codebase knowledge graph generator and architecture mapping guide. Instructs agents on AST dependency extraction and blast radius analysis.
 tags:
   - knowledge-graph
   - ast
@@ -11,3 +12,7 @@ version: 1.0.0
 optional:
   - context-manager
   - system-design
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - VALIDATION.json

package/.agents/core/skills/gstack-roles/SKILL.md

@@ -25,12 +25,14 @@ Inspired by [Garry Tan's gstack](https://github.com/garrytan/gstack) — shippin
 
 ## Role Identification Protocol
 
-At the start of each task, declare your role:
+At the start of each task or major phase switch, declare your role:
 
 ```
 [ROLE: <Role Name>] — <One-line description of your mandate for this task>
 ```
 
+> **Anti-Spam Invariant**: Declare this role **strictly once per phase**. Never prefix intermediate tool calls, file operations, or step updates with role tags.
+
 Then execute ONLY within the constraints of that role.
 
 ---

package/.agents/core/skills/gstack-roles/skill.yaml

@@ -1,4 +1,5 @@
 name: gstack-roles
+type: instruction-only
 description: >
   Role-based AI specialist system inspired by Garry Tan's gstack.
   Defines 23 specialist roles (CEO, Eng Manager, Designer, QA, Security etc.)
@@ -10,3 +11,8 @@ tags:
   - planning
 version: 1.0.0
 source: https://github.com/garrytan/gstack
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json

package/.agents/core/skills/impeccable-design/skill.yaml

@@ -1,4 +1,5 @@
 name: impeccable-design
+type: instruction-only
 description: >
   Visual design quality skill based on pbakaus/impeccable.
   46 deterministic anti-pattern rules that prevent AI design slop.
@@ -12,3 +13,8 @@ tags:
   - anti-patterns
 version: 1.0.0
 source: https://github.com/pbakaus/impeccable
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json