@jetrabbits/agentic 0.0.3 → 0.0.5

package/areas/software/security/prompts/security-scan.md

@@ -4,88 +4,80 @@ workflow: security-scan
 
 # Prompt: `/security-scan`
 
-Use when: running a full automated security sweep — SAST, dependency audit, secrets detection, IaC checks — before a release or after a major change.
+Use when: running a security scan that must produce actionable release decisions (`exploitable-now`, `not-reachable`, `accepted-risk`) rather than only raw scanner output.
 
 ---
 
-## Example 1 — Pre-release security gate
+## Example 1 — Release gate with reachability triage and VEX output
 
 **EN:**
 ```
 /security-scan
 
-Trigger: release candidate v2.5.0 ready for staging sign-off
-Scope: full — SAST + dependency CVEs + secrets + IaC (Terraform)
-Stack: Python 3.12 / FastAPI, PostgreSQL, Redis, Terraform (AWS)
-Tools available: bandit, ruff, safety, trufflehog, tfsec, semgrep
-Severity threshold: block release on any Critical or High; report Medium/Low
-Output: security-scan-report.md with findings, severity, remediation steps
-Branch: release/2.5.0
+Trigger: release candidate v4.2.0
+Scope: SAST + dependency + secrets + IaC
+Stack: Node.js 22, Python 3.12, Terraform
+Policy:
+  - Block release for any Critical finding classified as exploitable-now
+  - High findings require remediation plan <= 72h or time-bound exception
+Required output sections:
+  1) Findings summary by severity
+  2) Reachability analysis for each High/Critical dependency CVE
+  3) Classification table: exploitable-now / not-reachable / accepted-risk
+  4) VEX-style statements for not-reachable items with evidence
+  5) Exception register (owner, expiry, compensating controls)
 ```
 
 **RU:**
 ```
 /security-scan
 
-Триггер: release candidate v2.5.0 готов к sign-off на staging
-Скоуп: полный — SAST + CVE зависимостей + секреты + IaC (Terraform)
-Стек: Python 3.12 / FastAPI, PostgreSQL, Redis, Terraform (AWS)
-Доступные инструменты: bandit, ruff, safety, trufflehog, tfsec, semgrep
-Порог серьёзности: блокировать релиз на любом Critical или High; отчитываться о Medium/Low
-Результат: security-scan-report.md с находками, серьёзностью, шагами устранения
-Ветка: release/2.5.0
+Триггер: release candidate v4.2.0
+Скоуп: SAST + зависимости + секреты + IaC
+Стек: Node.js 22, Python 3.12, Terraform
+Политика:
+  - Блокировать релиз при любом Critical, классифицированном как exploitable-now
+  - Для High нужен план устранения <= 72ч или ограниченное по времени исключение
+Обязательные разделы результата:
+  1) Сводка находок по серьёзности
+  2) Reachability-анализ для каждого High/Critical dependency CVE
+  3) Таблица классификации: exploitable-now / not-reachable / accepted-risk
+  4) VEX-подобные записи для not-reachable с доказательствами
+  5) Реестр исключений (owner, expiry, compensating controls)
 ```
 
 ---
 
-## Example 2 — Post-incident targeted scan
+## Example 2 — Fast incident-mode scan focused on exploitability
 
 **EN:**
 ```
 /security-scan
 
-Trigger: post-incident — suspected SQL injection in orders module (INC-2024-088)
-Scope: targeted — SAST only on src/api/ and src/repositories/; dependency audit for SQLAlchemy
-Priority: SQL injection patterns, unsanitised inputs, ORM bypass risks
-Skip: IaC scan, secrets scan (already clean, saves time)
-Output: findings with code location + PoC query if reproducible
-Timeframe: results needed within 2 hours for incident postmortem
+Context: actively exploited CVE announced in a transitive dependency
+Timebox: 90 minutes
+Scope:
+  - Dependency path tracing to affected services
+  - Runtime reachability confirmation
+  - Exposure check for internet-facing routes
+Output:
+  - List of impacted services sorted by exploitability risk
+  - Immediate mitigations (feature flags, traffic isolation, WAF rules)
+  - Patch and rollback plan
 ```
 
 **RU:**
 ```
 /security-scan
 
-Триггер: после инцидента — подозрение на SQL injection в модуле orders (INC-2024-088)
-Скоуп: целевой — только SAST на src/api/ и src/repositories/; аудит зависимостей для SQLAlchemy
-Приоритет: паттерны SQL injection, неэкранированные входные данные, риски обхода ORM
-Пропустить: IaC сканирование, проверку секретов (уже чисто, экономия времени)
-Результат: находки с расположением кода + PoC запрос если воспроизводимо
-Срок: результаты нужны в течение 2 часов для postmortem инцидента
-```
-
----
-
-## Example 3 — Dependency-only quick scan
-
-**EN:**
-```
-/security-scan
-
-Scope: dependency CVE audit only
-Stack: Node.js 20 / Express, npm lockfile
-Command: npm audit --audit-level=high
-Auto-fix: apply non-breaking patches automatically (npm audit fix)
-Report: list packages with unresolved High/Critical CVEs that need manual review
-```
-
-**RU:**
-```
-/security-scan
-
-Скоуп: только аудит CVE зависимостей
-Стек: Node.js 20 / Express, npm lockfile
-Команда: npm audit --audit-level=high
-Авто-исправление: применить неломающие патчи автоматически (npm audit fix)
-Отчёт: список пакетов с неустранёнными High/Critical CVE которые требуют ручного ревью
+Контекст: опубликован активно эксплуатируемый CVE в транзитивной зависимости
+Таймбокс: 90 минут
+Скоуп:
+  - Трассировка dependency path до затронутых сервисов
+  - Подтверждение runtime reachability
+  - Проверка экспозиции интернет-facing маршрутов
+Результат:
+  - Список затронутых сервисов, отсортированный по риску exploitability
+  - Немедленные mitigation-шаги (feature flags, изоляция трафика, WAF rules)
+  - План патча и отката
 ```

package/areas/software/security/rules/dependency-policy.md

@@ -1,12 +1,47 @@
 # Rule: Dependency Security Policy
 
-**Priority**: P1 — Critical CVEs block deploy; High CVEs require plan within 72 hours.
+**Priority**: P1 — Critical exploitable dependency risk blocks release; all accepted risks require owner + expiry.
 
-## Constraints
+## Policy Model: Risk-Based, Not CVSS-Only
 
-1. **No direct use of packages with Critical CVEs**: Upgrade or replace immediately.
-2. **High CVEs**: Remediation plan within 72 hours.
-3. **Dependency audit in CI**: `npm audit`, `pip audit`, `trivy` run on every PR. Fail on severity ≥ HIGH.
-4. **Pin transitive dependencies**: Lockfiles committed to Git (`package-lock.json`, `poetry.lock`, `go.sum`).
-5. **No abandoned packages**: Packages without updates > 2 years require security review.
-6. **License compliance**: No GPL in closed-source products without legal review. MIT, Apache 2.0, BSD pre-approved.
+1. Triage by **exploitability context**:
+   - severity (CVSS),
+   - reachability from runtime code path,
+   - exposure boundary (internet-facing vs internal),
+   - presence of compensating controls.
+2. A Critical CVE with confirmed reachable path is a deployment blocker.
+3. High CVEs require remediation plan within 72h or formal exception.
+
+## Mandatory CI Controls
+
+4. Run dependency scanning on every PR and main build.
+5. Enforce lockfiles and deterministic install modes.
+6. Verify checksums/signatures when ecosystem tooling supports it.
+7. Fail on prohibited licenses or policy-violating dependency sources.
+
+## Provenance and Registry Trust
+
+8. Prefer trusted publishers / verified maintainers where available.
+9. Restrict package sources to approved registries/proxies.
+10. Alert on maintainer transfer, suspicious install scripts, typosquatting indicators.
+
+## Reachability and VEX
+
+11. For each High/Critical finding, classify as:
+   - `exploitable-now`,
+   - `not-reachable`,
+   - `accepted-risk` (temporary).
+12. Use VEX-compatible status where possible to document non-exploitable findings.
+13. “Not reachable” claims require evidence (call graph, dependency path, runtime boundary).
+
+## Exception Handling
+
+14. Exceptions require: owner, justification, compensating controls, expiry date (max 30 days).
+15. Expired exceptions automatically re-block deployments.
+16. All exceptions reviewed in weekly security triage.
+
+## Language/Stack Constraints
+
+17. JavaScript/TypeScript: lockfile mandatory; block lifecycle scripts unless explicitly approved.
+18. Python: hashes for production requirements (`--require-hashes`) when feasible.
+19. Containers: base images pinned by digest; no floating tags in production images.

package/areas/software/security/skills/dependency-audit/SKILL.md

@@ -2,28 +2,49 @@
 
 ## When to load
 
-When adding new packages, reviewing a PR that adds dependencies, or performing security reviews.
-
-## Pre-Add Checklist
-
-```
-Before npm install [package]:
-1. POPULARITY: > 100k weekly downloads?
-2. MAINTENANCE: Last commit within 12 months? Open PRs reviewed?
-3. OWNERSHIP: Well-known org/individual? History of incidents?
-4. SCOPE: Does the package scope match its stated purpose?
-          (A CSV parser with network dependencies is suspicious)
-5. AUDIT: Run npm audit / snyk test immediately after adding
-6. SIZE: Check bundlephobia.com
-7. ALTERNATIVES: Is there a built-in API that does this?
-```
-
-## Supply Chain Attack Red Flags
-
-```
-- Recently transferred ownership
-- Sudden version bump with no changelog
-- Minified/obfuscated code in source (not just dist)
-- postinstall / preinstall scripts making network requests
-- Name similar to popular package (typosquatting)
-```
+When adding/updating dependencies, handling security findings, preparing releases, or reviewing supply-chain risk in PRs.
+
+## Objective
+
+Produce a dependency risk decision based on exploitability and business impact, not scanner output alone.
+
+## Audit Workflow
+
+1. **Inventory**
+   - Identify direct and transitive dependencies changed in PR/release.
+   - Record package source (registry), maintainer trust indicators, and version deltas.
+
+2. **Scan**
+   - Run ecosystem-native audit tools + repository policy checks.
+   - Capture High/Critical findings with package path and affected components.
+
+3. **Exploitability Triage**
+   - Determine runtime reachability (is vulnerable code path invoked?).
+   - Evaluate exposure (public endpoint, privileged process, internal-only).
+   - Assess mitigations (WAF, sandbox, feature flags, auth boundaries).
+
+4. **Classify each finding**
+   - `exploitable-now` → block release, fix immediately.
+   - `not-reachable` → document evidence and add VEX status.
+   - `accepted-risk` → temporary exception with owner + expiry.
+
+5. **Remediation Plan**
+   - Prefer upgrade to patched version.
+   - If upgrade is breaking: isolate vulnerability, add compensating controls, schedule upgrade milestone.
+
+## Supply-Chain Red Flags
+
+- Maintainer transfer shortly before suspicious release.
+- Sudden dependency graph expansion unrelated to package purpose.
+- install/postinstall scripts performing unexpected network activity.
+- Obfuscated source in runtime package.
+- Package source not in approved registries.
+
+## Output Template (required)
+
+- Dependency name and version delta
+- Severity and advisory source
+- Reachability evidence
+- Classification (`exploitable-now` / `not-reachable` / `accepted-risk`)
+- Decision and next action
+- Owner and deadline

package/areas/software/security/skills/threat-modeling/SKILL.md

@@ -1,5 +1,16 @@
+---
+name: threat-modeling
+type: skill
+description: "Apply STRIDE threat modeling to system designs, identify IDOR and authorization vulnerabilities, and build threat matrices for security reviews. Use when the user designs a new system, reviews an architecture, prepares for a security audit, or asks about common API vulnerabilities like IDOR or broken access control."
+related-rules:
+  - security-baseline.md
+allowed-tools: Read, Bash
+---
+
 # Skill: Threat Modeling
 
+> **Expertise:** STRIDE framework, IDOR prevention, authorization boundary analysis, threat matrices for API and system security reviews.
+
 ## When to load
 
 When designing a new system, adding an integration, reviewing an architecture, or preparing for a security review.
@@ -15,6 +26,14 @@ When designing a new system, adding an integration, reviewing an architecture, o
 | **D**enial of Service | Can the service be made unavailable? | No rate limiting on public endpoints |
 | **E**levation of Privilege | Can a low-privilege user gain higher access? | IDOR, broken object-level authorization |
 
+## Threat Modeling Workflow
+
+1. **Identify assets** — list sensitive data, APIs, and trust boundaries in the system
+2. **Apply STRIDE** — walk through each threat category against every asset and boundary
+3. **Score risks** — rank by likelihood × impact (Critical / High / Medium / Low)
+4. **Prioritize mitigations** — address Critical/High first; document accepted risks for Medium/Low
+5. **Validate** — verify mitigations with code review, SAST/DAST scans, or penetration testing
+
 ## IDOR — Most Common API Vulnerability
 
 ```python
@@ -34,3 +53,10 @@ def get_invoice(invoice_id: int, current_user: User = Depends(get_current_user))
         raise HTTPException(status_code=404)  # 404, not 403
     return invoice
 ```
+
+## Common Mistakes
+
+- **Returning 403 instead of 404** — reveals that the resource exists, enabling enumeration
+- **Client-side authorization only** — always enforce ownership and role checks server-side
+- **Missing audit logs for sensitive actions** — makes repudiation threats undetectable
+- **Trusting internal service-to-service calls** — apply zero-trust; validate JWTs at every boundary

package/docs/agentic-lifecycle.md

@@ -0,0 +1,103 @@
+# Installed CLI lifecycle
+
+This guide describes how an installed `agentic` binary resolves and updates its knowledge base checkout.
+
+## Paths
+
+`agentic` uses XDG-compatible defaults:
+
+- Config home: `${XDG_CONFIG_HOME:-$HOME/.config}`
+- Data home: `${XDG_DATA_HOME:-$HOME/.local/share}`
+- Config directory: `~/.config/agentic`
+- Config file: `~/.config/agentic/config`
+- OpenCode plugin config: `~/.config/agentic/opencode-plugins.json`
+- Knowledge base data directory: `~/.local/share/agentic`
+- Knowledge base checkout: `~/.local/share/agentic/repo`
+
+The config file currently stores the selected theme:
+
+```ini
+theme=auto
+```
+
+Supported values are `auto`, `dark`, and `light`.
+
+Target projects receive `.agentic.json`. It stores selected install settings, managed file paths, source paths, hashes, generated marker type, and skipped files from the latest rerun.
+
+## Repository modes
+
+`agentic` supports two repository source modes:
+
+1. Dev mode: when `agentic` runs from a real `agent-guides` checkout and can find sibling `areas/`, `extensions/`, and `AGENTS.md`, it uses the local repository directly.
+2. Installed mode: when the binary is installed to a standalone path such as `~/.local/bin/agentic`, it uses `~/.local/share/agentic/repo` as knowledge base checkout.
+
+## Bootstrap
+
+In installed mode, commands that need repository data clone the checkout on first use:
+
+```bash
+git clone https://github.com/sawrus/agent-guides.git ~/.local/share/agentic/repo
+```
+
+After cloning, `agentic` validates that the checkout contains:
+
+- `areas/`
+- `extensions/`
+- `AGENTS.md`
+
+Commands that auto-bootstrap when needed:
+
+- `agentic list ...`
+- `agentic install ...`
+- `agentic tui`
+- `agentic upgrade`
+
+## Upgrade flow
+
+Refresh the knowledge base checkout with:
+
+```bash
+agentic upgrade
+```
+
+Behavior:
+
+- If `~/.local/share/agentic/repo` does not exist, `agentic upgrade` performs initial clone.
+- If checkout already exists, `agentic` runs:
+
+```bash
+git -C ~/.local/share/agentic/repo pull --ff-only
+```
+
+In dev mode, `upgrade` targets the active local checkout instead of `~/.local/share/agentic/repo`.
+
+In installed mode, after the checkout is updated, `agentic upgrade` copies `~/.local/share/agentic/repo/agentic` over the running installed binary when the contents differ. This keeps future `agentic upgrade` runs able to update both the knowledge base and the local executable.
+
+If a user already has an older installed binary that cannot self-update, do not ask them to run `agentic self-install --force` from `$PATH`: that invokes the old binary. Use one of these recovery paths:
+
+From a fresh `agent-guides` checkout, run from the repository root:
+
+```bash
+./agentic self-install --force
+```
+
+Or refresh through the bootstrap installer, which downloads a fresh script before installing:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/sawrus/agent-guides/main/install | bash -s -- --force
+```
+
+After the knowledge base is updated, `agentic upgrade` checks the current working directory for `.agentic.json`. If present, it treats the directory as an already managed project, reloads the recorded `agent_os`, `areas`, and `specializations`, and reruns the install sync against the upgraded knowledge base.
+
+The project sync follows the same manifest protection as `agentic install`: user-modified managed files are skipped, existing unmanaged files are not overwritten, and new generated files from the upgraded knowledge base are added when their target path does not already exist.
+
+## Managed reruns
+
+When `.agentic.json` exists in the target project, `agentic install` treats the project as already managed:
+
+- only files listed in `.agentic.json` are eligible for update;
+- files whose current hash differs from the stored hash are skipped as user-modified;
+- new hashes are written for successfully updated managed files;
+- skipped paths are recorded in `.agentic.json`.
+
+Every copied or generated file carries an internal marker. Markdown uses YAML front matter, comment-capable formats use comments, and JSON uses an `_agentic` object.

package/docs/agentic-token-minimization/README.md

@@ -0,0 +1,79 @@
+# Agentic Token-Minimization Upgrade
+
+This feature reduces the amount of guidance copied into target projects while making future `agentic` reruns safer.
+
+## Managed Files
+
+After installation, `agentic` writes `.agentic.json` in the target project root. The file records:
+
+- selected agent OS targets, areas, and specializations;
+- source repository and checkout path;
+- every file managed by `agentic`;
+- each managed file's source path and SHA-256 hash;
+- skipped files from the latest rerun.
+
+When `agentic` runs again in a project with `.agentic.json`, it updates only files listed in that manifest. If a managed file hash no longer matches the last `agentic` write, the file is treated as user-modified and is skipped.
+
+## Generated Markers
+
+Every copied or generated file is marked internally:
+
+- Markdown files receive `agentic` metadata in YAML front matter.
+- TypeScript, shell, TOML, Python, YAML, CSS, and similar text formats receive a valid comment.
+- JSON files receive an `_agentic` metadata object because JSON does not allow comments.
+
+The marker includes `generated_by: agentic`, the source path, and `https://github.com/sawrus/agent-guides`.
+
+## OpenCode Optional Plugins
+
+When installing for OpenCode, `agentic` writes optional plugin state to:
+
+```text
+~/.config/agentic/opencode-plugins.json
+```
+
+Interactive installs ask whether to enable Telegram notifications and model checking. Non-interactive installs default optional plugins to disabled when no config exists.
+
+The OpenCode plugins read this config at startup and return no hooks when disabled. Telegram credentials can also be supplied through:
+
+```text
+OPENCODE_TELEGRAM_BOT_TOKEN
+OPENCODE_TELEGRAM_CHAT_ID
+```
+
+## Context7
+
+`agentic` adds Context7 MCP configuration for known project-level formats:
+
+- `opencode.json`
+- `.opencode/opencode.json` for backward compatibility with existing generated OpenCode extension config
+- `.codex/config.toml`
+- `.mcp.json` for Claude Code project-scoped MCP servers
+- `.cursor/mcp.json`
+- `.gemini/settings.json`
+
+Interactive installs ask whether to enable Context7. If enabled, the Context7 API key is optional. Empty keys keep the install usable with default Context7 limits or rule-only fallback behavior. Non-interactive installs enable Context7 only when `CONTEXT7_API_KEY` is already set. Generated guidance requires agents to use Context7 for framework, SDK, library, and API documentation before relying on model memory when the project config is present.
+
+Directory copies are processed in batches so large specialization installs avoid spawning a separate marker/manifest process for every copied file. Manifest protection still applies: existing unmanaged files are skipped on rerun, user-modified managed files are skipped, and new generated files can be added by newer `agentic` versions.
+
+## Full-Stack Skill Budget
+
+`areas/software/full-stack/skills` is capped at six core skills:
+
+- `api-design-principles`
+- `api-patterns`
+- `app-builder`
+- `backend-developer`
+- `blackbox-test`
+- `prompt-project-planner`
+
+This keeps task-specific context smaller while preserving workflow coverage.
+
+## Quality Audit
+
+`scripts/assess_area_quality.py` scores every specialization by environment. It writes:
+
+- `reports/area-quality.json`
+- `reports/area-quality.md`
+
+The audit is warn-first by default. A strict threshold can be enabled through its CLI flags, but project verification should invoke it through Makefile targets.

package/docs/agentic-usage.md

@@ -0,0 +1,145 @@
+# agentic CLI usage
+
+This guide covers day-to-day use of the `agentic` CLI.
+
+For lifecycle and repository resolution details, see [Installed CLI lifecycle](agentic-lifecycle.md).
+
+## Run modes
+
+Run from a local checkout:
+
+```bash
+./agentic
+```
+
+Run directly with NPX (no prior install):
+
+```bash
+npx @jetrabbits/agentic@latest
+```
+
+Run the installed binary:
+
+```bash
+agentic
+```
+
+Default behavior:
+
+- In an interactive terminal: starts TUI mode
+- In non-interactive mode (CI/pipe): prints usage and exits with code `1`
+- For CI one-off execution, prefer `npx @jetrabbits/agentic@latest <command>`
+
+Install the standalone binary:
+
+```bash
+./agentic self-install
+```
+
+For users with an old installed `agentic`, do not run `agentic self-install --force` from `$PATH`: that invokes the old binary and may try to copy itself over itself. From a fresh `agent-guides` checkout, run from the repository root instead:
+
+```bash
+./agentic self-install --force
+```
+
+Recover or update an already installed binary without relying on the old local copy:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/sawrus/agent-guides/main/install | bash -s -- --force
+```
+
+Common options:
+
+- `--bin-dir <dir>`: install into a custom binary directory
+- `--force`: overwrite an existing target binary
+- `--install-fzf`: optionally try auto-installing `fzf` during self-install
+- `--dry-run`: show actions without writing files
+
+## Core commands
+
+Start TUI:
+
+```bash
+agentic tui
+```
+
+Install guidance into a project:
+
+```bash
+agentic install \
+  --project-dir /path/to/your-project \
+  --agent-os opencode,codex \
+  --areas software \
+  --specializations software.general,software.backend
+```
+
+After install, `agentic` writes `.agentic.json` in the target project. It records copied/generated files and their hashes. A later install rerun updates only manifest-managed files and skips files changed by the user.
+
+List available options:
+
+```bash
+agentic list agentos
+agentic list areas
+agentic list specs --area software
+```
+
+Refresh the local knowledge base checkout:
+
+```bash
+agentic upgrade
+```
+
+In installed mode, `agentic upgrade` also refreshes the installed `agentic` binary from the updated knowledge base checkout. If an older binary cannot self-update, use the `curl ... | bash -s -- --force` bootstrap command above once.
+
+## TUI and `fzf`
+
+TUI uses `fzf` for interactive selection. If `fzf` is missing, `agentic` can:
+
+1. ask permission to auto-install it
+2. fall back to index-based menus if install is declined or fails
+
+`--install-fzf` only affects `self-install`. If auto-install fails, self-install still completes.
+
+Manual install examples:
+
+Linux:
+
+```bash
+sudo apt-get install -y fzf
+```
+
+macOS:
+
+```bash
+brew install fzf
+```
+
+Windows (run from Git Bash):
+
+```bash
+winget install --id junegunn.fzf -e
+# or
+choco install fzf -y
+# or
+scoop install fzf
+```
+
+## OpenCode optional plugins
+
+When `opencode` is selected, interactive installs ask whether to enable Telegram notifications and the model checker. The answer is stored globally in:
+
+```text
+~/.config/agentic/opencode-plugins.json
+```
+
+Non-interactive installs create a disabled config when no config exists. Telegram can also read `OPENCODE_TELEGRAM_BOT_TOKEN` and `OPENCODE_TELEGRAM_CHAT_ID`.
+
+## Context7
+
+For `opencode` and `codex`, interactive installs ask whether to add project-level Context7 MCP configuration. If enabled, the Context7 API key prompt is optional; leave it empty to configure Context7 without a key.
+
+Non-interactive installs skip Context7 unless `CONTEXT7_API_KEY` is set in the environment. Agents are instructed to use Context7 for framework, library, SDK, API, and setup documentation when the project config is present.
+
+## Deprecated wrapper
+
+`agentos-install.sh` remains for backward compatibility and forwards to `agentic`. Prefer `agentic` in new usage and documentation.