@jetrabbits/agentic 0.0.3 → 0.0.5

package/docs/catalog.schema.json

@@ -0,0 +1,203 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-guides.local/schemas/catalog.schema.json",
+  "title": "Agent Guides Docs Catalog",
+  "type": "object",
+  "required": [
+    "version",
+    "generated_from",
+    "areas",
+    "stats"
+  ],
+  "properties": {
+    "version": {
+      "type": "string"
+    },
+    "generated_from": {
+      "type": "string"
+    },
+    "areas": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "area",
+          "workflows"
+        ],
+        "properties": {
+          "area": {
+            "type": "string"
+          },
+          "workflows": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "trigger",
+                "name",
+                "description",
+                "workflow_path",
+                "inputs",
+                "outputs",
+                "roles",
+                "related_rules",
+                "uses_skills",
+                "quality_gates",
+                "examples",
+                "skill_refs"
+              ],
+              "properties": {
+                "trigger": {
+                  "type": "string"
+                },
+                "name": {
+                  "type": "string"
+                },
+                "description": {
+                  "type": "string"
+                },
+                "workflow_path": {
+                  "type": "string"
+                },
+                "prompt_path": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "use_when": {
+                  "type": "string"
+                },
+                "inputs": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "outputs": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "roles": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "related_rules": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "uses_skills": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "quality_gates": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "examples": {
+                  "type": "object",
+                  "required": [
+                    "both"
+                  ],
+                  "properties": {
+                    "both": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "required": [
+                          "number",
+                          "title",
+                          "en",
+                          "ru"
+                        ],
+                        "properties": {
+                          "number": {
+                            "type": "integer",
+                            "minimum": 1
+                          },
+                          "title": {
+                            "type": "string"
+                          },
+                          "en": {
+                            "type": "string"
+                          },
+                          "ru": {
+                            "type": "string"
+                          }
+                        }
+                      }
+                    }
+                  }
+                },
+                "prompt_command_refs": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "skill_refs": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "required": [
+                      "name",
+                      "path"
+                    ],
+                    "properties": {
+                      "name": {
+                        "type": "string"
+                      },
+                      "path": {
+                        "type": [
+                          "string",
+                          "null"
+                        ]
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "stats": {
+      "type": "object",
+      "required": [
+        "workflows",
+        "prompts",
+        "problems",
+        "matched_prompts"
+      ],
+      "properties": {
+        "workflows": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "prompts": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "problems": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "matched_prompts": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    }
+  }
+}

package/docs/guidance-updates/2026-04-10-software-devops-best-practices.md

@@ -0,0 +1,26 @@
+# Guidance Update — Software & DevOps Best Practices (2026-04-10)
+
+## Summary
+
+This update strengthens repository guidance in five high-impact areas:
+
+1. Supply-chain security moved to keyless-first signing, attestations, and admission enforcement.
+2. Release workflow upgraded with database compatibility gates, progressive delivery, and explicit rollback criteria.
+3. Dependency security moved from CVSS-only to exploitability-aware triage with exception governance.
+4. Backend/full-stack security rules expanded for modern cloud-native threats and service identity controls.
+5. Observability and alerting standards aligned to SLO-first operations with burn-rate policy and telemetry cost controls.
+
+## Why this update
+
+- Reduce production risk from software supply-chain and dependency compromise.
+- Improve release safety for schema and high-risk feature changes.
+- Align operational controls with modern SRE and platform governance practices.
+- Increase actionability and signal quality in observability/alerting.
+
+## Impacted areas
+
+- `areas/devops/ci-cd/*`
+- `areas/software/security/*`
+- `areas/software/full-stack/rules/security-guide.md`
+- `areas/software/backend/rules/security.md`
+- `areas/devops/observability/rules/*`

package/docs/opencode_prepare_agents.md

@@ -0,0 +1,40 @@
+# TASK: Prepare AI Agent Infrastructure
+
+Analyze the codebase and create a complete AI-agent setup, including `AGENTS.md` and the `.agent/` directory.
+
+## STEP 1: Project analysis
+
+Collect the following details:
+
+1. **Technology stack**
+   - Programming language (Python/Go/Node.js/Java/Rust)
+   - Framework (FastAPI/Django/Express/Spring/Gin/Actix)
+   - Database (PostgreSQL/MySQL/MongoDB/Redis)
+   - Build tools (poetry/npm/cargo/maven/gradle)
+
+2. **Commands**
+   - Dependency installation
+   - Linting and formatting
+   - Testing (full suite, single file, single test)
+   - Build and run
+
+3. **Architecture and domain**
+   - Service boundaries/modules
+   - Core entities and relationships
+   - External integrations and infrastructure
+
+## STEP 2: Create guidance artifacts
+
+Create:
+
+- `AGENTS.md` (high-level operating guidance)
+- `.agent/rules/*` (non-negotiable constraints)
+- `.agent/skills/*/SKILL.md` (focused execution playbooks)
+- `.agent/workflows/*` (repeatable delivery flows)
+- `.agent/prompts/*` (ready-to-use commands/prompts)
+
+## STEP 3: Quality checks
+
+- Ensure guidance matches the real stack and tooling.
+- Keep instructions actionable and testable.
+- Verify examples are technically accurate and production-oriented.

package/docs/opencode_setup.md

@@ -0,0 +1,45 @@
+# OpenCode setup
+
+## Configuration
+
+The main OpenCode configuration file is located at:
+
+```text
+~/.config/opencode/opencode.json
+```
+
+## Authentication
+
+### Auth files
+
+OpenCode stores authentication data in two locations:
+
+| Path | Description |
+|------|-------------|
+| `~/.config/opencode/` | Plugin-level credentials (for example, `antigravity-accounts.json`) |
+| `~/.local/share/opencode/auth.json` | Primary provider tokens (OpenAI, Google, and others) |
+
+## Notes
+
+- Back up credentials before machine migration.
+- Keep auth files out of version control.
+- Prefer least-privilege API keys for automation.
+
+## Agentic optional plugins
+
+When `agentic` installs the OpenCode extension, it configures optional plugins in:
+
+```text
+~/.config/agentic/opencode-plugins.json
+```
+
+Telegram notifications and model checking are opt-in. If the config is absent or a plugin is disabled, the plugin returns no hooks and OpenCode continues without that behavior.
+
+Telegram notifications use either the stored config values or these environment variables:
+
+```text
+OPENCODE_TELEGRAM_BOT_TOKEN
+OPENCODE_TELEGRAM_CHAT_ID
+```
+
+Non-interactive `agentic install` defaults optional plugins to disabled when no config exists.

package/docs/prompt-format.md

@@ -0,0 +1,80 @@
+# Prompt format standard (EN/RU)
+
+This repository expects every `areas/**/prompts/*.md` file to follow a strict structure so docs generation can reliably extract examples.
+
+## Required structure
+
+1. YAML front matter:
+
+```md
+---
+workflow: your-workflow-stem
+---
+```
+
+2. Prompt header:
+
+```md
+# Prompt: `/your-workflow-stem`
+```
+
+3. Use-when line:
+
+```md
+Use when: short scenario.
+```
+
+4. Two or three examples:
+
+```md
+## Example 1 — Human-readable title
+
+**EN:**
+```
+/prompt-command
+...
+```
+
+**RU:**
+```
+/prompt-command
+...
+```
+```
+
+## Rules
+
+- `workflow:` in front matter is mandatory and must match a sibling file in `workflows/<workflow>.md`.
+- Prompt filename must match the workflow stem, e.g. `prompts/testing-ci-pipeline.md` for `workflows/testing-ci-pipeline.md`.
+- Prompt header and every slash command inside examples must be canonical and match the workflow stem, e.g. `/testing-ci-pipeline`.
+- `Workflow link command:` is deprecated and must not appear.
+- Every example must include **both** EN and RU fenced code blocks.
+- Every prompt must contain **2 or 3** examples.
+- Keep command and input payload realistic and copy-paste ready.
+- Prefer concise titles for examples.
+- Generic scaffold placeholders such as `<project context>` are not allowed.
+
+## Validation
+
+Run local format checks:
+
+```bash
+python3 scripts/lint_prompts.py
+```
+
+Run full catalog consistency checks:
+
+```bash
+python3 scripts/build_docs_catalog.py --validate
+```
+
+
+## Mapping logic
+
+Catalog builder links prompts to workflows using the prompt front matter key:
+
+```yaml
+workflow: workflow-file-name
+```
+
+Validation then requires prompt filename, header command, and example commands to match that same workflow stem.

package/docs/site/README.md

@@ -0,0 +1,44 @@
+# Markdown docs site (search + menu)
+
+This prototype renders a documentation site directly from markdown-derived catalog data.
+
+## Why this stack
+
+The user requirement was: site from markdown with search and menu. We evaluated popular GitHub projects:
+
+- docsify: https://github.com/docsifyjs/docsify
+- MkDocs: https://github.com/mkdocs/mkdocs
+- Docusaurus: https://github.com/facebook/docusaurus
+- markdown-it (parser): https://github.com/markdown-it/markdown-it
+
+For this repo we keep it lightweight and dependency-minimal:
+
+- catalog is generated offline by Python script from `areas/**/{workflows,prompts}`
+- site is static HTML/CSS/JS
+- markdown rendering via `marked` CDN
+- full-text search via `lunr` CDN
+
+## Run locally
+
+```bash
+python3 scripts/build_docs_catalog.py --output docs/site/catalog.json --validate
+python3 -m http.server 8000
+# open http://localhost:8000/docs/site/
+```
+
+## Features
+
+- Left menu grouped by area.
+- Full-text search by trigger/name/description/examples.
+- Language switcher: EN only / RU only / EN+RU.
+- Workflow page with quality gates and source paths.
+
+
+## GitHub Pages
+
+This site can be published from GitHub Pages via Actions workflow (`.github/workflows/docs-site.yml`).
+
+
+## Workflow mapping
+
+Prompt-to-workflow mapping is command-based: `/workflow-file-name` in prompt text links to `workflows/<workflow-file-name>.md` in the same area.

package/docs/site/app.js

@@ -0,0 +1,127 @@
+let catalog;
+let current = null;
+let idx;
+let docs = [];
+
+const menuEl = document.getElementById('menu');
+const contentEl = document.getElementById('content');
+const searchEl = document.getElementById('search');
+const langEl = document.getElementById('language');
+
+init();
+
+async function init() {
+  const res = await fetch('./catalog.json');
+  catalog = await res.json();
+  buildIndex();
+  renderMenu(catalog.areas);
+  if (docs[0]) renderWorkflow(docs[0].id);
+}
+
+function buildIndex() {
+  docs = [];
+  for (const area of catalog.areas) {
+    for (const wf of area.workflows) {
+      docs.push({
+        id: `${area.area}:${wf.trigger}`,
+        area: area.area,
+        trigger: wf.trigger,
+        name: wf.name,
+        description: wf.description,
+        examples: (wf.examples?.both || []).map((e) => `${e.en}\n${e.ru}`).join('\n'),
+        data: wf,
+      });
+    }
+  }
+
+  idx = lunr(function () {
+    this.ref('id');
+    this.field('area');
+    this.field('trigger');
+    this.field('name');
+    this.field('description');
+    this.field('examples');
+    docs.forEach((d) => this.add(d));
+  });
+}
+
+function renderMenu(areas, filteredIds = null) {
+  menuEl.innerHTML = '';
+  for (const area of areas) {
+    const title = document.createElement('div');
+    title.className = 'area-title';
+    title.textContent = area.area;
+    menuEl.appendChild(title);
+
+    for (const wf of area.workflows) {
+      const id = `${area.area}:${wf.trigger}`;
+      if (filteredIds && !filteredIds.has(id)) continue;
+      const btn = document.createElement('button');
+      btn.className = 'wf-btn';
+      btn.textContent = `${wf.trigger} — ${wf.name}`;
+      btn.onclick = () => renderWorkflow(id);
+      menuEl.appendChild(btn);
+    }
+  }
+}
+
+function renderWorkflow(id) {
+  current = docs.find((d) => d.id === id);
+  if (!current) return;
+  const wf = current.data;
+  const lang = langEl.value;
+
+  const examples = (wf.examples?.both || []).map((ex) => {
+    const blocks = [];
+    if (lang === 'both' || lang === 'en') blocks.push(`**EN**\n\n\
+\`\`\`\n${escapeFence(ex.en)}\n\`\`\``);
+    if (lang === 'both' || lang === 'ru') blocks.push(`**RU**\n\n\
+\`\`\`\n${escapeFence(ex.ru)}\n\`\`\``);
+    return `### Example ${ex.number} — ${ex.title}\n\n${blocks.join('\n\n')}`;
+  }).join('\n\n');
+
+  const md = `
+# ${wf.name}  
+\`${wf.trigger}\`
+
+${wf.description || ''}
+
+**Use when:** ${wf.use_when || '—'}
+
+## Roles
+${(wf.roles || []).map((r) => `<span class="chip">${r}</span>`).join(' ')}
+
+## Quality gates
+${(wf.quality_gates || []).map((q) => `- ${q}`).join('\n') || '- —'}
+
+## Skills
+${(wf.skill_refs || []).map((s) => `- ${s.name} (${s.path || "missing"})`).join('\n') || '- —'}
+
+## Examples (${lang.toUpperCase()})
+${examples || '_No examples_'}
+
+---
+
+<div class="meta">Workflow source: <code>${wf.workflow_path}</code><br/>Prompt source: <code>${wf.prompt_path || '—'}</code></div>
+`;
+
+  contentEl.innerHTML = marked.parse(md);
+}
+
+function escapeFence(s) {
+  return (s || '').replace(/```/g, '\\\`\\\`\\\`');
+}
+
+searchEl.addEventListener('input', () => {
+  const q = searchEl.value.trim();
+  if (!q) {
+    renderMenu(catalog.areas);
+    return;
+  }
+  const results = idx.search(`${q}*`);
+  renderMenu(catalog.areas, new Set(results.map((r) => r.ref)));
+});
+
+langEl.addEventListener('change', () => {
+  if (current) renderWorkflow(current.id);
+});