@jetrabbits/agentic 0.0.3 → 0.0.5

package/AGENTS.md

@@ -60,6 +60,21 @@ Cross-cutting practices that apply to every project regardless of area.
 - 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.
+- Before changing project logic, read the relevant design and behavior documents under `docs/**`.
+- Run validation, tests, coverage, and CI-style checks through Makefile targets only.
+
+### Documentation of Behavior Changes
+
+- Any behavior change captured in Markdown artifacts must be documented under the project `docs/` directory.
+- Use documentation paths that match the change type, for example `docs/<feature>/README.md` for feature behavior and `docs/incidents/<date>-<workload>-root-cause.md` for incident root cause reports.
+- Create or update the relevant `docs/` artifact in the same change set; do not leave behavior changes documented only in workflow outputs, tickets, or PR comments.
+- Apply the `product-owner` role to confirm that docs describe the user-facing behavior, acceptance criteria, and operational constraints of the change.
+
+### Context7 Knowledge Source
+
+- Use Context7 for framework, library, SDK, API, and setup documentation before relying on model memory.
+- Resolve the library or framework identity first, then request focused docs for the exact task and version when version matters.
+- If Context7 is unavailable, state that explicitly and fall back to local docs or official project documentation.
 
 ### Code Style
 

package/Makefile

@@ -0,0 +1,40 @@
+.PHONY: help install dev test lint fmt clean build assess-areas
+
+help:
+	@printf '%s\n' \
+		"Available targets:" \
+		"  install       Install local development prerequisites" \
+		"  dev           Show local development entrypoints" \
+		"  test          Run end-to-end tests" \
+		"  lint          Run prompt and catalog validation" \
+		"  fmt           Check formatting hooks placeholder" \
+		"  clean         Remove generated reports" \
+		"  build         Build generated docs catalog" \
+		"  assess-areas  Generate area quality scorecards"
+
+install:
+	@printf '%s\n' "No install step required."
+
+dev:
+	@printf '%s\n' "Use ./agentic tui or ./agentic install ..."
+
+test:
+	bash tests/e2e/agentic.e2e.sh
+
+lint:
+	bash -n agentic
+	python3 -m py_compile scripts/build_docs_catalog.py scripts/lint_prompts.py scripts/assess_area_quality.py
+	python3 scripts/lint_prompts.py --strict
+	python3 scripts/build_docs_catalog.py --validate --output /tmp/agentic-catalog-check.json
+
+fmt:
+	@printf '%s\n' "No formatter configured."
+
+clean:
+	rm -f reports/area-quality.json reports/area-quality.md
+
+build:
+	python3 scripts/build_docs_catalog.py --output docs/site/catalog.json --validate
+
+assess-areas:
+	python3 scripts/assess_area_quality.py --json-output reports/area-quality.json --markdown-output reports/area-quality.md

package/README.md

@@ -8,6 +8,7 @@ and prompts into any project — and run a full SDLC agent team out of the box.
 - [Website](https://sawrus.github.io/agent-guides/)
 - [Coverage scorecard](https://claude.ai/public/artifacts/8177bc3d-3b2f-48a6-8232-47c5b02b20f3)
 - [CLI usage guide](docs/agentic-usage.md)
+- [NPM package](https://www.npmjs.com/package/@jetrabbits/agentic)
 
 ## Coverage snapshot
 

package/UPGRADE.md

@@ -0,0 +1,61 @@
+# Agentic Knowledge Maintenance
+
+This guide defines how to update `areas/**` so copied agentic artifacts stay practical, current, and token-efficient.
+
+## Weekly Upgrade Workflow
+
+1. Pick one specialization at a time, for example `areas/software/full-stack`.
+2. Read its `AGENTS.md`, all workflow front matter, prompt examples, and the current `docs/site/catalog.json` entry.
+3. Identify one concrete industry change worth adding: a new delivery practice, framework release pattern, testing method, security control, observability practice, or operational runbook step.
+4. Convert the change into the smallest useful artifact:
+   - Rule: mandatory cross-cutting constraint agents must always follow.
+   - Skill: task-specific procedure loaded only when needed.
+   - Workflow: multi-role SDLC sequence with inputs, outputs, owners, gates, and failure path.
+   - Prompt: examples that trigger an existing workflow with realistic project context.
+5. Run the area quality audit and prompt/catalog checks through Makefile targets.
+6. Document the behavior change under `docs/guidance-updates/` or a more specific `docs/<feature>/` path.
+
+## What Qualifies As Useful Knowledge
+
+- It changes an agent decision or action in a target project.
+- It has a measurable quality gate, command, checklist, schema, or handoff.
+- It is specific to a domain, stack, SDLC phase, or operational risk.
+- It helps a developer get better implementation, review, verification, rollout, or incident response.
+
+Avoid adding:
+
+- Generic advice that a modern LLM already knows.
+- Long explanations without a command, decision rule, or acceptance criterion.
+- Duplicate guidance already present in a parent area.
+- Tool-specific setup that should live in `extensions/**` or `docs/**` instead.
+
+## Area Update Checklist
+
+- `AGENTS.md` remains a navigation map, not a knowledge dump.
+- Rules use imperative language and contain enforceable constraints.
+- Skills explain when to load them and keep detailed references in separate files only when needed.
+- Workflows define roles, `execution.initiator`, inputs, outputs, `uses-skills`, quality gates, and a failure loop.
+- Prompts include two or three realistic EN/RU examples with concrete systems, symptoms, constraints, and expected deliverables.
+- All `uses-skills` entries resolve to existing `skills/<name>/SKILL.md`.
+- Token budget is improved or justified: remove stale skills before adding new ones.
+
+## Practical SDLC Additions To Look For
+
+- Requirements: acceptance criteria templates, non-goal capture, compatibility and migration constraints.
+- Design: API contract review, data model risk, UX state inventory, security threat paths.
+- Implementation: framework-specific safe defaults, dependency upgrade patterns, migration sequencing.
+- Verification: contract tests, blackbox flows, accessibility checks, performance budgets, CI gates.
+- Deployment: rollout strategy, rollback steps, feature flags, monitoring, release notes.
+- Maintenance: runbooks, postmortem templates, cost/performance review, dependency freshness.
+
+## Quality Bar
+
+An update is ready only when it gives the target-project agent enough context to act without guessing:
+
+- what to inspect;
+- which role owns the step;
+- what command or artifact to produce;
+- what pass/fail condition applies;
+- where the behavior is documented under `docs/`.
+
+If an update cannot pass that bar, keep it out of `areas/**` until it becomes actionable.