@jetrabbits/agentic 0.0.4 → 0.0.5

package/areas/software/full-stack/AGENTS.md

@@ -49,11 +49,8 @@ full-stack/
 │   ├── api-patterns/SKILL.md            ← auth, rate limiting, versioning, tRPC
 │   ├── app-builder/SKILL.md             ← project scaffolding, templates, tech stack detection
 │   ├── backend-developer/SKILL.md       ← service patterns, DI, repository design
-│   ├── python-pro/SKILL.md              ← Python idioms, packaging, async patterns
-│   ├── bash-pro/SKILL.md                ← shell scripting, automation, CI helpers
 │   ├── blackbox-test/SKILL.md           ← external API testing, contract validation
-│   ├── prompt-project-planner/SKILL.md  ← project planning, milestone scoping
-│   └── skill-creator/SKILL.md           ← authoring new skills for this repo
+│   └── prompt-project-planner/SKILL.md  ← project planning, milestone scoping
 ├── workflows/
 │   ├── develop-feature.md              ← /develop-feature
 │   ├── debug-issue.md                  ← /debug-issue

package/areas/software/full-stack/workflows/debug-issue.md

@@ -22,8 +22,8 @@ related-rules:
   - testing-ci-guide.md
   - logging-observability-guide.md
 uses-skills:
-  - troubleshooting
-  - observability
+  - backend-developer
+  - blackbox-test
 quality-gates:
   - bug reproducible before fix
   - regression test fails before fix, passes after

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.

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.