@event4u/agent-config 1.9.1

package/.agent-src/skills/grafana/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: grafana
+description: "Use when working with Grafana — dashboards, Loki LogQL queries, alerting rules, monitoring panels — even when the user just says 'build me a dashboard' or 'query the logs' without naming Grafana."
+source: package
+---
+
+# Grafana Skill
+
+## When to use
+
+Use this skill when:
+- Creating or editing Grafana dashboards (JSON provisioning)
+- Writing Loki LogQL queries for log analysis
+- Configuring alerting rules or contact points
+- Working on a Grafana module (if the project has one)
+- Debugging log-based issues using Loki data
+
+## Procedure: Create Grafana dashboard
+
+### Project setup
+
+Check if the project has a dedicated Grafana module or Docker config. Typical structure:
+
+```
+{grafana-location}/
+├── .docker/
+│   ├── grafana/
+│   │   ├── dashboards/              ← Dashboard JSON files (provisioned)
+│   │   ├── provisioning/
+│   │   │   ├── datasources/         ← Loki, Prometheus data sources
+│   │   │   └── dashboards/          ← Dashboard provisioning config
+│   │   └── alerting/                ← Alert rules, contact points, notification policies
+│   └── loki/
+│       └── loki-config.yml          ← Loki server configuration
+├── App/
+│   ├── Logging/                     ← Loki timestamp processors
+│   └── Console/Commands/            ← GrafanaPushDashboardsCommand
+├── Docs/
+│   └── Loki.md                      ← Loki documentation
+└── Routes/console.php
+```
+
+### Configuration
+
+- **Grafana config:** `config/grafana.php`
+- **Logging channels:** `config/logging.php` (Loki channels)
+- **Loki package:** `itspire/monolog-loki` via Monolog handler
+
+## Dashboard conventions
+
+### JSON provisioning
+
+Dashboards are stored as JSON in `.docker/grafana/dashboards/` and auto-provisioned.
+Use `GrafanaPushDashboardsCommand` to push dashboards to remote Grafana instances.
+
+### Panel rules
+
+- **Always hide Loki metadata columns** in table panels:
+  `labelTypes`, `traceID`, `traceID (field)` → add to `excludeByName` in the `organize` transformation.
+- **Verify column names match data semantics:** If the timestamp represents `imported_at`,
+  name the column "Imported", not "Uploaded".
+- **Use consistent time ranges:** Default to "Last 24 hours" for operational dashboards.
+- **Add variables** for customer FQDN, environment, and time range filters.
+
+### Naming
+
+| Element | Convention | Example |
+|---|---|---|
+| Dashboard title | Descriptive, Title Case | "Import Overview (Loki)" |
+| Panel title | Short, descriptive | "Import Results by Status" |
+| Variable names | lowercase, underscore | `$fqdn`, `$environment` |
+
+## Loki LogQL
+
+### Query patterns
+
+```logql
+# Filter by service and status
+{service="import_result"} |= "DONE" | json | status = "DONE"
+
+# Count by label
+sum by (status) (count_over_time({service="import_result"} | json [$__interval]))
+
+# Filter by customer FQDN
+{service="import_result", fqdn=~"$fqdn"} | json
+```
+
+### Service labels
+
+| Label | Purpose | Notes |
+|---|---|---|
+| `import_result` | Final import states (DONE, FAILED) | Use for result dashboards |
+| `import_snapshot` | Cron-based status snapshots | Use for timeline dashboards |
+| `service=import` | Legacy static label | Do NOT query — use specific labels above |
+
+### Best practices
+
+- Use `json` parser for structured log entries
+- Use `line_format` for human-readable output in explore view
+- Use `$__interval` for rate/count queries (auto-adjusts to time range)
+- Filter early in the pipeline (labels before line filters before parsers)
+
+## Alerting
+
+### Structure
+
+```
+.docker/grafana/alerting/
+├── alert-rules.yml          ← Alert conditions and thresholds
+├── contact-points.yml       ← Notification targets (Slack, email)
+└── notification-policies.yml ← Routing rules (which alerts → which contacts)
+```
+
+### Conventions
+
+- Alert names: descriptive, include severity: "Import Failure Rate > 10% (Critical)"
+- Use `for` duration to avoid flapping (e.g., `for: 5m`)
+- Group related alerts by folder/namespace
+
+## Integration with logging
+
+The project uses structured logging via Monolog → Loki:
+
+- **`LokiTimestampProcessor`** — Adds precise timestamps to log entries
+- **`LokiTimestampChannelTap`** — Configures Loki channels with timestamp processing
+- **Import events** are logged via `ImportEventLogger` service
+
+When adding new log entries for Grafana visualization:
+1. Use a dedicated log channel (defined in `config/logging.php`)
+2. Log as JSON with consistent field names
+3. Add appropriate Loki labels for filtering
+4. Update or create a dashboard panel for the new data
+
+## Related
+
+- **Skill:** `logging-monitoring` — full monitoring stack overview
+- **Skill:** `dashboard-design` — visualization selection, layout, KPI strategies
+- **Skill:** `traefik` — HTTPS for Grafana embedding in the app
+- Check the project for Grafana module or Docker config location
+- **Config:** `config/grafana.php`, `config/logging.php` (if applicable)
+
+
+## Output format
+
+1. Grafana dashboard JSON or LogQL/PromQL queries
+2. Panel configuration with data source and thresholds
+3. Alert rule definitions where applicable
+
+## Gotcha
+
+- Loki queries use LogQL, not PromQL — the syntax is different despite looking similar.
+- Don't create alerts without a clear notification channel — silent alerts are useless.
+- Dashboard panels that query too much data (>7 days at full resolution) will timeout — use downsampling.
+
+## Do NOT
+
+- Do NOT create panels without proper units and labels.
+- Do NOT use alerting rules without a notification channel.
+- Do NOT hardcode datasource names — use variables.
+
+## Auto-trigger keywords
+
+- Grafana
+- Loki
+- dashboard
+- log query
+- alerting
+- monitoring panel

package/.agent-src/skills/guideline-writing/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: guideline-writing
+description: "Use when creating or editing a guideline in .agent-src.uncompressed/guidelines/ — reference material cited by skills, no auto-triggers — even when the user just says 'write up our naming conventions'."
+source: package
+---
+
+# guideline-writing
+
+## When to use
+
+* Creating a new guideline in `.agent-src.uncompressed/guidelines/{topic}/{name}.md`
+* Rewriting an existing guideline (not a typo fix)
+* Extracting reference material out of a bloated skill or rule
+* Consolidating repeated explanations from multiple skills
+
+Do NOT use this skill when:
+
+* The content is a constraint ("never / always") → use `rule-writing`
+* The content is a triggered workflow → use `skill-writing`
+* The content is a user-invoked action → use `command-writing`
+
+## Guideline vs rule vs skill — critical test
+
+| Intent | Artifact |
+|---|---|
+| "Here is knowledge skills and rules may cite" | **Guideline** |
+| "Agent must always / never do X" | **Rule** |
+| "When Y happens, run these steps" | **Skill** |
+
+A guideline is **reference material**. It is never a trigger. It has no
+`description` used for routing — skills and rules link to it.
+
+## Procedure
+
+### 0. Run the Drafting Protocol
+
+Creating or materially rewriting a guideline **must** go through Understand
+→ Research → Draft from the
+[`artifact-drafting-protocol`](../../rules/artifact-drafting-protocol.md) rule.
+
+* **Understand** — which skills or rules will cite this guideline? If the
+  answer is "none", the guideline has no home — stop.
+* **Research** — **inspect** `guidelines/` for overlap and grep
+  `.agent-src.uncompressed/` for pages that already cover the topic.
+  **Analyze** 1–2 peer guidelines in the same topic folder for tone.
+* **Draft** — propose location (topic folder + filename) and outline. Only
+  fill bodies once the outline is confirmed.
+
+### 1. Pick the right topic folder
+
+Folders under `.agent-src.uncompressed/guidelines/`:
+
+| Folder | Contents |
+|---|---|
+| `agent-infra/` | Cross-cutting agent-system knowledge (naming, size, output patterns) |
+| `php/` | PHP-specific reference (patterns, services, jobs, resources) |
+| `e2e/` | End-to-end testing patterns |
+
+If none fits, ask the user before creating a new folder.
+
+### 2. Write frontmatter
+
+Guidelines use a minimal frontmatter — no `type`, no auto-trigger semantics.
+
+```yaml
+---
+description: "Short human-readable summary — cited by skills, not used for routing"
+source: package     # or project for consumer-local guidelines
+---
+```
+
+If you do want to polish the description for a guideline whose summary
+gets surfaced to agents, delegate to the
+[`description-assist`](../description-assist/SKILL.md) skill — same
+approval-gated flow as for skills and rules.
+
+### 3. Structure the body
+
+* Start with a single `#` heading that matches the filename.
+* Organize by topic, not by workflow — no numbered procedures.
+* Prefer tables, bullet lists, and short code blocks over prose paragraphs.
+* End with explicit "See also" links to related guidelines and the skills
+  that cite it.
+
+### 4. Wire it in
+
+A guideline is useless if nothing cites it. Before closing the task:
+
+* Add a link from at least one skill or rule using the pattern
+  `→ See 'guidelines/{topic}/{name}.md' for full X`.
+* Keep the citing skill/rule **executable** — do not hollow it out into a
+  pointer. (Normative source: [`preservation-guard`](../../rules/preservation-guard.md).)
+
+### 5. Enforce the size budget
+
+Guidelines have more room than rules but are not dumping grounds.
+
+| Category | Target |
+|---|---|
+| Ideal | ≤ 200 lines |
+| Acceptable | ≤ 400 lines |
+| Split signal | > 500 lines |
+
+Above the split signal, break by sub-topic into sibling files in the same folder.
+
+### 6. Validate
+
+* Run `python3 scripts/skill_linter.py .agent-src.uncompressed/guidelines/{topic}/{name}.md`
+  → 0 FAIL (guidelines have relaxed linting but must still parse).
+* Run `task sync` → regenerates `.agent-src/guidelines/`.
+* Run `python3 scripts/check_references.py` → no broken links.
+* Run `task ci` → exits 0 except for tolerated warnings.
+
+## Output format
+
+1. Complete guideline at `.agent-src.uncompressed/guidelines/{topic}/{name}.md`
+2. At least one skill or rule linking to it
+3. Linter + `check_references.py` clean
+4. `task sync` confirmation
+
+## Gotchas
+
+* Creating a guideline nothing cites → dead page, remove or inline.
+* Pasting a workflow into a guideline → that is a skill, not reference.
+* Duplicating content already present in another guideline or skill →
+  extract into the guideline and link from both.
+* Hollowing out a skill into "see guideline" — the skill must remain
+  executable (see `preservation-guard`).
+
+## Do NOT
+
+* Do NOT add `type:` or `alwaysApply:` to the frontmatter
+* Do NOT embed numbered procedures — those belong in skills
+* Do NOT create an orphan guideline with no inbound links
+* Do NOT edit `.agent-src/guidelines/` or `.augment/guidelines/` — generated
+
+## Examples
+
+Good guideline name + description:
+
+> Path: `guidelines/agent-infra/size-and-scope.md`
+> Description: "Golden size rules for rules, skills, commands, and guidelines"
+
+Bad:
+
+> Path: **guidelines/stuff** (no topic folder, meaningless stem)
+> Description: "Things to know"

package/.agent-src/skills/jira-integration/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: jira-integration
+description: "Use when the user says "check Jira", "create ticket", "update issue", or needs JQL queries, ticket transitions, or branch-to-ticket linking."
+source: package
+---
+
+# Jira Skill
+
+## When to use
+
+Use this skill when:
+- Reading a Jira ticket for context (bug reports, feature requests)
+- Creating new Jira issues from discovered bugs or planned work
+- Transitioning ticket status (e.g., "In Progress" → "In Review")
+- Writing JQL queries to find related issues
+- Linking branches or PRs to Jira tickets
+
+
+Do NOT use when:
+- GitHub Issues (use `github-api` tool directly)
+- Linear or other issue trackers
+
+## Procedure: Work with Jira
+
+1. **Identify action** — Search, read, create, update, or transition a ticket?
+2. **Use the correct endpoint** — See API table below.
+3. **Execute** — Make the API call with required fields.
+4. **Verify** — Confirm the response contains expected data or the ticket was updated.
+
+| Tool | Purpose |
+|---|---|
+| `jira-integration` (GET `/search/jql`) | Search issues with JQL |
+| `jira-integration` (GET `/issue/{key}`) | Read a specific ticket |
+| `jira-integration` (POST `/issue`) | Create a new ticket |
+| `jira-integration` (PUT `/issue/{key}`) | Update a ticket |
+| `jira-integration` (GET `/issue/{key}/transitions`) | Get available status transitions |
+| `jira-integration` (POST `/issue/{key}/transitions`) | Transition ticket status |
+| `jira-integration` (POST `/issue/{key}/comment`) | Add a comment |
+| `jira-integration` (GET `/project`) | List projects |
+| `jira-integration` (GET `/field`) | List available fields (check before writing JQL) |
+
+## Branch-to-ticket detection
+
+Extract ticket IDs from branch names automatically:
+
+```
+feat/DEV-1234/user-notifications  →  DEV-1234
+fix/DEV-5678/null-pointer         →  DEV-5678
+hotfix/DEV-999/critical-fix       →  DEV-999
+```
+
+Pattern: `[A-Z]+-[0-9]+` anywhere in the branch name.
+
+Use `git branch --show-current` to detect, then fetch the ticket:
+
+```
+jira GET /issue/DEV-1234
+```
+
+## JQL patterns
+
+### Common queries
+
+```jql
+# My open tickets
+assignee = currentUser() AND status != Done ORDER BY priority DESC
+
+# Tickets in current sprint
+project = DEV AND sprint in openSprints() AND assignee = currentUser()
+
+# Recently updated bugs
+project = DEV AND type = Bug AND updated >= -7d ORDER BY updated DESC
+
+# Tickets by component
+project = DEV AND component = "Import" AND status != Done
+```
+
+### Tips
+
+- Always check available fields first: `GET /field`
+- Use `currentUser()` for the authenticated user
+- Use `sprint in openSprints()` for current sprint
+- JQL is case-insensitive for field names but case-sensitive for values
+
+## Creating tickets
+
+### Required fields
+
+Always check issue types first: `GET /issue/createmeta/{project}/issuetypes`
+
+Minimum fields for creation:
+- `project` — project key (e.g., `DEV`)
+- `issuetype` — issue type (Bug, Task, Story, etc.)
+- `summary` — short title
+
+### Description format (ADF)
+
+Jira uses Atlassian Document Format for descriptions:
+
+```json
+{
+  "version": 1,
+  "type": "doc",
+  "content": [
+    {
+      "type": "paragraph",
+      "content": [
+        { "type": "text", "text": "Description text here." }
+      ]
+    }
+  ]
+}
+```
+
+### Attribution
+
+Always add attribution when creating issues or comments:
+
+```
+Co-authored by Augment Code
+```
+
+With link to `https://www.augmentcode.com/?utm_source=atlassian&utm_medium=jira_issue&utm_campaign=jira`
+
+## Status transitions
+
+Before transitioning, always get available transitions first:
+
+```
+GET /issue/DEV-1234/transitions
+```
+
+Then transition with the correct ID:
+
+```json
+POST /issue/DEV-1234/transitions
+{ "transition": { "id": "31" } }
+```
+
+**Important:** Never transition without explicit user permission (see `rules/no-commit.md` — same principle applies to ticket status changes).
+
+## Linking to PRs
+
+When creating PRs, include the Jira ticket in:
+- **Branch name:** `feat/DEV-1234/description`
+- **PR title:** `feat(DEV-1234): description`
+- **PR description:** Link to the ticket
+
+## Related
+
+- **Skill:** `bug-analyzer` — uses Jira as input source for bug investigation
+- **Skill:** `feature-planning` — uses Jira for feature context
+- **Command:** `/bug-investigate` — auto-detects Jira tickets from branch
+- **Command:** `/feature-plan` — auto-detects Jira tickets from branch
+- **Rule:** `no-commit.md` — never change ticket status without permission
+
+
+## Output format
+
+1. Jira ticket data presented in structured format
+2. Ticket key, summary, status, and relevant fields
+
+## Gotcha
+
+- Jira field names are case-sensitive in JQL — `status` works, `Status` doesn't.
+- Don't create duplicate tickets — always search first with JQL before creating.
+- The model tends to forget that Jira description uses ADF (Atlassian Document Format), not Markdown.
+- `accountId` is required for assignee — display name alone doesn't work in the API.
+
+## Do NOT
+
+- Do NOT change ticket status without explicit user permission.
+- Do NOT create tickets without checking for duplicates.
+
+## Auto-trigger keywords
+
+- Jira
+- ticket
+- issue
+- JQL
+- workflow transition
+- sprint

package/.agent-src/skills/jobs-events/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: jobs-events
+description: "Use when creating Laravel jobs, queued workflows, events, or listeners. Covers clear responsibilities, safe serialization, and retry/failure handling."
+source: package
+---
+
+# jobs-events
+
+## When to use
+
+Use when creating jobs, events, listeners, or queued workflows.
+
+Do NOT use when:
+- Artisan commands (use `artisan-commands` skill)
+- Scheduling configuration (use `laravel-scheduling` skill)
+
+## Procedure: Create a Job
+
+### Step 0: Inspect
+
+1. Check existing jobs — match naming, queue config, retry strategy, failure handling.
+2. Determine sync vs. async — only queue work that is slow, retryable, or non-blocking.
+3. Check queue driver: `.env` / `config/queue.php` (Redis, database, sync).
+4. Check Horizon: `config/horizon.php` for queue names, supervisors, balancing.
+
+### Step 1: Create the job class
+
+1. Pass IDs or compact DTOs in constructor — not full models with relations.
+2. Set queue via `$this->onQueue(Queue::NAME->value)`.
+3. Add `tags()` for Horizon filtering.
+4. Set `$maxExceptions`, `backoff()`, `$uniqueFor` as needed.
+
+### Step 2: Implement handle()
+
+1. Keep focused and readable.
+2. Delegate complex logic to services/actions.
+3. Design for idempotency — retries must not create duplicates.
+
+### Step 3: Test
+
+- `Bus::fake()`, `Queue::fake()`, `Event::fake()`.
+- Test side effects, not just dispatch assertions.
+
+## Procedure: Create an Event + Listener
+
+### Step 1: Create event
+
+- Past-tense naming: `OrderPlaced`, `ImportCompleted`.
+- Keep payload focused.
+- Laravel 11+: automatic discovery — no manual registration.
+
+### Step 2: Create listener
+
+- One responsibility per listener.
+- Delegate large logic to services.
+- Use `ShouldQueue` on listeners that do heavy work.
+
+## Conventions
+
+→ See guideline `php/jobs.md` for full conventions (serialization, idempotency, events, dispatching).
+
+## Output format
+
+1. Job/Event/Listener class(es) with proper serialization and retry config
+2. Event registration in EventServiceProvider if needed
+
+## Gotcha
+
+- Without `ShouldQueue`, jobs run synchronously.
+- Queued jobs serialize constructor args — don't pass loaded models.
+- Listener exceptions block the event chain — queue heavy listeners.
+- Set `$tries` and `$backoff` — unlimited retries overwhelm the queue.
+
+## Do NOT
+
+- Do NOT serialize Eloquent models with loaded relations into queued jobs.
+- Do NOT ignore idempotency — retries must not create duplicates.
+- Do NOT hide critical business flows behind deep listener chains.
+
+## Auto-trigger keywords
+
+- Laravel job
+- queue
+- event
+- listener
+- dispatch
+- serialization