@jetrabbits/agentic 0.0.1

package/AGENTS.md

@@ -0,0 +1,143 @@
+# AGENTS — root guidance
+
+## Dynamic loading of guidance
+
+The set of loaded guidance is configurable per project and may change per task. Do not assume only statically listed files are available.
+
+Discover and load custom files from the target project when present:
+
+```text
+project_dir/
+└── .agent/
+    ├── rules/
+    ├── skills/
+    ├── workflows/
+    └── prompts/
+```
+
+**Discovery patterns:**
+
+- `project_dir/.agent/rules/*`
+- `project_dir/.agent/skills/*`
+- `project_dir/.agent/workflows/*`
+- `project_dir/.agent/prompts/*`
+
+Prefer relative paths in references inside markdown files.
+
+---
+
+## Area and spec selection
+
+When starting a task, resolve the correct area and spec by matching the task domain:
+
+| Domain | Area |
+|:---|:---|
+| API / service / backend logic | `areas/software/backend/` |
+| UI / components / frontend | `areas/software/frontend/` |
+| Full product feature (API + UI) | `areas/software/full-stack/` |
+| Data pipelines, dbt, warehouses | `areas/software/data-engineering/` |
+| ML training, serving, monitoring | `areas/software/mlops/` |
+| iOS / Android / cross-platform | `areas/software/mobile/` |
+| Internal platform, K8s, Terraform | `areas/software/platform/` |
+| Test strategy, QA tooling | `areas/software/qa/` |
+| Threat modeling, secure coding | `areas/software/security/` |
+| Kubernetes cluster operations | `areas/devops/kubernetes/` |
+| CI/CD pipelines | `areas/devops/ci-cd/` |
+| IaC, environment provisioning | `areas/devops/infrastructure/` |
+| Observability, dashboards, alerts | `areas/devops/observability/` |
+| SLOs, incidents, chaos | `areas/devops/sre/` |
+| Networking, ingress, TLS, mesh | `areas/devops/networking/` |
+| DevSecOps, supply-chain security | `areas/devops/devsecops/` |
+| DB operations, backup, migrations | `areas/devops/database-ops/` |
+| Cross-cutting / foundational | `areas/software/general/` |
+
+If the task spans multiple areas, load the primary area's full chain and add only the `rules/*` from secondary areas.
+
+---
+
+## Load order (always respected)
+
+1. This root `AGENTS.md`
+2. Area `AGENTS.md` (e.g., `areas/software/backend/AGENTS.md`)
+3. Spec `rules/*.md` — load all rules for the selected spec
+4. Spec `skills/*/SKILL.md` — load only the skill matching the current task (see "When to load" in each skill)
+5. Spec `workflows/*.md` — load the workflow matching the slash command trigger
+
+---
+
+## General Development Practices
+
+Cross-cutting practices that apply to every project regardless of area.
+
+### Git Workflow
+
+- Use feature branches with task IDs in branch names (e.g., `feat/TASK-123-add-auth`).
+- Commit messages include context: what changed, why, and any relevant ticket reference.
+- No direct commits to main or protected branches — all changes via reviewed PRs.
+
+### Makefile Conventions
+
+- Use Makefile for common development tasks accessible to all contributors.
+- Include a `help` target listing available commands with descriptions.
+- Standard targets: `install`, `dev`, `test`, `lint`, `fmt`, `clean`, `build`.
+
+### Docker Compose
+
+- Use docker-compose for local multi-service development.
+- Configure health checks for all dependent services before marking ready.
+- Drive configuration via environment variables; no hardcoded values.
+
+### Linting and Formatting
+
+- Configure language-appropriate linters for every project.
+- Enforce standards via pre-commit hooks — CI is a safety net, not the primary check.
+- Apply consistent formatting across all files on every commit.
+
+### SDLC Methodology
+
+- Follow phases in order: Requirements → Design → Implementation → Verification → Deployment → Maintenance.
+- Document requirements before implementation — "we'll figure it out" is not a requirement.
+- Conduct design reviews for any change with architectural, security, or data model impact.
+
+### Code Style
+
+- Write self-documenting code with meaningful names — comments explain why, not what.
+- Apply DRY principles; avoid duplication across modules.
+- Keep functions focused on a single responsibility; extract when a function does two things.
+
+---
+
+## Repository Exploration (mandatory before implementation)
+
+Before executing any workflow, spawn a subagent to explore the repository.
+
+### Role resolution
+
+- Use the role defined in `execution.initiator` of the current workflow.
+- If not defined, use the role assigned to the first workflow step.
+- Resolve roles only from the current workflow's `roles` section — do not invent roles.
+
+### Purpose
+
+- Understand current architecture and established conventions.
+- Identify key modules, entrypoints, and data flows.
+- Detect configuration (env, Docker, Makefile, CI).
+- Identify components impacted by the proposed change.
+- Validate feasibility before any code is written.
+
+### Subagent responsibilities
+
+- Analyze repository structure and dependencies.
+- Locate relevant services, modules, and data flows.
+- Identify constraints, risks, and integration points.
+- Prepare a context summary for the next workflow step.
+
+### Required output
+
+- High-level system overview.
+- List of affected modules and files.
+- Detected risks and constraints.
+
+### Constraint
+
+This step is **mandatory** and must complete before "Solution Design & Risk Plan" begins.

package/README.md

@@ -0,0 +1,154 @@
+# agent-guides
+
+**agentic = Agent Intelligence Configuration.**
+
+A unified catalog of agentic specializations and the `agentic` CLI. The repository provides orchestrator-ready rules, skills, workflows, and prompts that can be installed into a target project from either a local checkout or an installed binary in `~/.local/bin`.
+
+- [Coverage scorecard](https://claude.ai/public/artifacts/8177bc3d-3b2f-48a6-8232-47c5b02b20f3)
+- [Website](https://sawrus.github.io/agent-guides/)
+
+---
+
+## What this is
+
+agent-guides is a structured knowledge base for AI coding agents. Instead of writing long system prompts, you install focused, composable guidance files that agents load on demand based on the task at hand.
+
+Each **area** (e.g., `devops/kubernetes`) provides:
+
+| File type | Purpose | When loaded |
+|:---|:---|:---|
+| `AGENTS.md` | Navigation index, load order, constraints | First — always |
+| `rules/*.md` | Hard constraints the agent must follow | Always, for the active spec |
+| `skills/*/SKILL.md` | Technical capabilities and patterns | On demand, matching "When to load" |
+| `workflows/*.md` | Orchestrated step-by-step processes | On `/command` trigger |
+| `prompts/*.md` | Human copy-paste templates (EN + RU) | Reference / paste |
+
+---
+
+## Repository structure
+
+```text
+agent-guides/
+├── areas/
+│   ├── software/              # Application development
+│   │   ├── general/           # Shared baseline — all software specs inherit from here
+│   │   ├── backend/           # REST/GraphQL APIs, services, database access
+│   │   ├── frontend/          # Components, accessibility, performance, CSS
+│   │   ├── full-stack/        # End-to-end product features
+│   │   ├── data-engineering/  # dbt, warehouses, pipelines, streaming
+│   │   ├── mlops/             # Training, evaluation, serving, monitoring
+│   │   ├── mobile/            # iOS, Android, React Native, Flutter
+│   │   ├── platform/          # K8s manifests, IaC, CI/CD, secrets
+│   │   ├── qa/                # Test strategy, coverage, flakiness, performance
+│   │   └── security/          # Threat modeling, SAST/DAST, auth, compliance
+│   └── devops/                # Platform and operations
+│       ├── kubernetes/        # Cluster bootstrap, workload ops, RBAC, upgrades
+│       ├── ci-cd/             # GitHub Actions, GitLab CI, quality gates, supply chain
+│       ├── infrastructure/    # Terraform, Ansible, IaC standards, drift detection
+│       ├── observability/     # Prometheus, Loki, Tempo, Grafana, SLOs
+│       ├── sre/               # SLOs, error budgets, incidents, chaos engineering
+│       ├── networking/        # Ingress, TLS, service mesh, DNS, VPC
+│       ├── devsecops/         # Shift-left, SBOM, OPA/Kyverno, container hardening
+│       └── database-ops/      # PostgreSQL, Redis, migrations, backup/restore
+├── extensions/
+│   ├── opencode/              # opencode agent definitions, commands, skills
+│   ├── claude/                # Claude-specific configs
+│   ├── antigravity/           # Antigravity platform configs
+│   ├── codex/                 # Codex override configs
+│   └── gemini/                # Gemini-specific configs
+├── areas/template/            # Authoring templates — start here for new content
+├── docs/                      # Setup and usage guides
+├── AGENTS.md                  # Root agent guidance (loaded into every project)
+└── agentic                    # CLI installer
+```
+
+---
+
+## Quick start
+
+### Install
+
+```bash
+npx @jetrabbits/agentic@latest
+```
+
+Alternative bootstrap (installs local binary):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/sawrus/agent-guides/main/install | bash
+```
+
+### Run
+
+```bash
+agentic
+```
+
+### Full instructions
+
+- [CLI usage guide](docs/agentic-usage.md)
+- [Installed CLI lifecycle](docs/agentic-lifecycle.md)
+
+---
+
+## Agents (opencode)
+
+The `extensions/opencode/agents/` directory defines the SDLC agent team:
+
+| Agent | Role | Mode |
+|:---|:---|:---|
+| `product-owner` | Value definition, scope, acceptance | primary |
+| `pm` | Planning, dependencies, stakeholder comms | subagent |
+| `team-lead` | Technical strategy, architecture, quality gates | subagent |
+| `developer` | Implementation, tests, delivery | subagent |
+| `qa` | Verification, risk classification, go/no-go | subagent |
+| `designer` | UX quality, interaction design, accessibility | subagent |
+| `devops-engineer` | Infrastructure, CI/CD, platform reliability | subagent |
+
+Each agent has:
+- A `vibe` — one-line personality hook.
+- An `Identity` section — personality, memory, and experience.
+- A `Communication Style` section — how to report, flag, and escalate.
+- `Success Metrics` — measurable criteria for a well-functioning agent.
+
+---
+
+## What gets installed where
+
+Running `agentic` in a target project installs guidance into the project's `.agent/` directory, making it discoverable by supported agent tools (opencode, Claude Code, Cursor, etc.).
+
+```text
+project/.agent/
+├── rules/       ← constraints active for every task in this project
+├── skills/      ← capabilities loaded on demand
+├── workflows/   ← processes triggered by slash commands
+└── prompts/     ← human-paste templates
+```
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for authoring standards, templates, and the pull request process.
+
+Quick checklist before opening a PR:
+- [ ] Used the appropriate template from `areas/template/`.
+- [ ] No `{{PLACEHOLDER}}` values remain.
+- [ ] Spec map in `AGENTS.md` updated.
+- [ ] Constraints in rules use imperative language.
+- [ ] Prompt examples include both EN and RU blocks.
+
+### Publishing to npm from GitHub Actions
+
+The publish workflow (`.github/workflows/publish-npm.yml`) expects a repository secret named `NPM_TOKEN`.
+
+- Use an **npm Automation token** (classic), or
+- Use a **granular npm access token** with package publish permission and **bypass 2FA enabled**.
+
+Without one of those token types, npm publish from CI fails with `E403` (`Two-factor authentication or granular access token with bypass 2fa enabled is required to publish packages`).
+
+---
+
+## License
+
+See [LICENSE](LICENSE) if present, or contact the maintainers.