@event4u/agent-config 1.9.1

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

@@ -0,0 +1,148 @@
+---
+name: rule-writing
+description: "Use when creating or editing a rule in .agent-src.uncompressed/rules/ — trigger wording, always vs auto classification, size budget — even when the user just says 'add a rule for X'."
+source: package
+---
+
+# rule-writing
+
+## When to use
+
+* Creating a new rule in `.agent-src.uncompressed/rules/{name}.md`
+* Rewriting an existing rule (not a typo fix)
+* Deciding whether something should be a rule at all
+* Converting a learning from `learning-to-rule-or-skill` into a concrete rule
+
+Do NOT use this skill when:
+
+* The content is a multi-step workflow → use `skill-writing`
+* The content is reference material agents cite → use `guideline-writing`
+* The content is a user-invoked action → use `command-writing`
+
+## Rule vs skill vs guideline — critical test
+
+| Intent | Artifact |
+|---|---|
+| "Agent must always/never do X" | **Rule** |
+| "When Y happens, run these steps" | **Skill** |
+| "Here is knowledge the agent may cite" | **Guideline** |
+
+A rule is a **constraint** — it states a boundary, not a workflow. If the
+content needs numbered steps, it is a skill.
+
+## Procedure
+
+### 0. Run the Drafting Protocol
+
+Creating or materially rewriting a rule **must** go through Understand →
+Research → Draft from the
+[`artifact-drafting-protocol`](../../rules/artifact-drafting-protocol.md) rule.
+
+* **Understand** — which agent behavior is wrong today? What should change?
+  Can you point to a concrete incident or repeated pattern?
+* **Research** — **inspect** `.agent-src.uncompressed/rules/` for overlap
+  and **analyze** `rule-type-governance`, `size-enforcement`,
+  `skill-quality` before drafting.
+* **Draft** — propose frontmatter (`type`, `description`) first, wait for
+  confirmation, then fill the body.
+
+### 1. Classify type — `always` vs `auto`
+
+Normative source: [`rule-type-governance`](../../rules/rule-type-governance.md).
+
+* `always` — universal behavior (language, scope, safety, verification)
+* `auto` — triggered by description match on domain/symptom
+
+Default to `auto`. `always` must be justified — if >50% of conversations
+don't need it, it is `auto`.
+
+### 2. Write a trigger-style description
+
+The `description` field **is** the trigger. Describe **when** the rule
+applies, not **what** it contains. Soft cap: **200 characters**.
+
+```yaml
+# Bad — describes content, won't match reliably:
+description: "PHP coding standards"
+
+# Good — trigger-shaped, names domain + symptoms:
+description: "Writing or reviewing PHP code — strict types, naming, comparisons, early returns, Eloquent conventions"
+```
+
+When iterating on phrasing, delegate to the
+[`description-assist`](../description-assist/SKILL.md) skill — approval-gated,
+no silent edits, max two rounds.
+
+### 3. Write the rule body
+
+* Short, constraint-only, easy to scan.
+* Bullet lists, tables, do/don't blocks — not paragraphs of prose.
+* No numbered procedures — if you need steps, it is a skill.
+* Link out to guidelines for deep reference instead of inlining them.
+
+### 4. Enforce the size budget
+
+Normative source: [`size-enforcement`](../../rules/size-enforcement.md) +
+`guidelines/agent-infra/size-and-scope.md`.
+
+| Category | Target |
+|---|---|
+| Ideal | < 60 non-empty lines |
+| Acceptable | < 100–120 lines |
+| Hard limit | < 200 lines |
+
+Linter emits `long_rule` above ~80 non-empty lines. Above that, justify in
+the PR or split by responsibility.
+
+### 5. Validate
+
+* Run `python3 scripts/skill_linter.py .agent-src.uncompressed/rules/{name}.md`
+  → must report **0 FAIL**.
+* Run `task sync` to regenerate `.agent-src/rules/{name}.md`.
+* Run `task generate-tools` to project into `.claude/`, `.cursor/`, `.clinerules/`, `.windsurfrules`.
+* Run `task ci` — must exit 0 except for tolerated warnings.
+
+## Frontmatter shape
+
+```yaml
+---
+type: "auto"              # or "always"
+description: "Trigger-shaped sentence — domain + symptoms — soft cap 200 chars"
+alwaysApply: false        # true only if type: always
+source: package           # or project for consumer-local rules
+---
+```
+
+## Output format
+
+1. Complete rule file at `.agent-src.uncompressed/rules/{name}.md`
+2. Frontmatter fully populated, no placeholders left
+3. Linter output showing 0 FAIL
+4. Confirmation that `task sync` + `task generate-tools` ran clean
+
+## Gotchas
+
+* Writing a rule that duplicates an existing one — always grep first.
+* Defaulting to `always` "just in case" — token cost is real, `auto` is default.
+* Description like "Rule about X" — it must describe *when*, not *what*.
+* Pasting a workflow into a rule — if it has numbered steps, split into a skill.
+* Forgetting to run `task generate-tools` — downstream tools stay stale.
+* Editing `.agent-src/rules/` or `.augment/rules/` directly — those are generated.
+
+## Do NOT
+
+* Do NOT inline long procedures
+* Do NOT exceed the hard size limit without an explicit waiver
+* Do NOT edit projections (`.agent-src/`, `.augment/`, `.claude/`, etc.)
+* Do NOT skip the linter
+* Do NOT create a rule when a guideline or skill is the right shape
+
+## Examples
+
+Good description (trigger-shaped, names domain + symptoms):
+
+> "Git commit message format, branch naming, conventional commits, committing, pushing, or creating pull requests"
+
+Bad description (no trigger, too vague):
+
+> "Commit conventions"

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

@@ -0,0 +1,79 @@
+---
+name: security
+description: "Use when applying security best practices — authentication, authorization via Policies, CSRF protection, input sanitization, rate limiting, or secure coding."
+source: package
+---
+
+# security
+
+## When to use
+
+Use when implementing authentication, authorization, or any security-sensitive functionality.
+
+Do NOT use when:
+- Validation logic only (use `laravel-validation` skill)
+- Full security audit (use `security-audit` skill)
+
+## Procedure: Implement security for a feature
+
+### Step 0: Inspect
+
+1. Read `agents/authentication.md` for auth flow.
+2. Read `agents/gates.md` for gate/policy patterns.
+3. Check existing policies in `app/Policies/`.
+
+### Step 1: Authentication
+
+- Check auth setup: `tymon/jwt-auth` or `laravel/sanctum`.
+- Check `config/auth.php` for guards and providers.
+- Customer identification happens after auth — see `multi-tenancy` skill.
+
+### Step 2: Authorization
+
+1. Create policy in `app/Policies/` if needed.
+2. Use in FormRequest `authorize()` or controller `$this->authorize()`.
+3. Check `agents/gates.md` for non-model gates.
+
+### Step 3: Review for adversarial
+
+For security-sensitive changes, run `adversarial-review` skill.
+Focus on: attack surface, trusting user input, authorization gaps.
+
+## Conventions
+
+→ See guideline `php/security.md` for auth, SQL injection, XSS, CSRF, headers, session, mass assignment.
+
+### Validate
+
+- Verify all user input is validated via FormRequest before use.
+- Confirm authorization check exists (Policy or Gate) for every state-changing action.
+- Check that no raw user input reaches SQL, HTML output, or shell commands.
+- Run PHPStan — must pass (catches type-safety issues that enable injection).
+
+## Output format
+
+1. Security-hardened code with auth, validation, and sanitization
+2. Policy class for authorization if needed
+
+## Gotcha
+
+- Validation ensures format, not intent — don't trust input after validation alone.
+- `Gate::authorize()` throws, `Gate::allows()` returns bool — choose based on error handling.
+- Rate limiting: ALL public endpoints, not just login.
+- Never log passwords, tokens, or API keys.
+
+## Do NOT
+
+- Do NOT bypass FormRequest validation in controllers.
+- Do NOT use `$request->all()` for mass assignment — use `$request->validated()`.
+- Do NOT store plaintext passwords or secrets in the database.
+- Do NOT expose internal error details in production API responses.
+
+## Auto-trigger keywords
+
+- security
+- authentication
+- authorization
+- CSRF
+- XSS
+- policy

package/.agent-src/skills/security-audit/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: security-audit
+description: "ONLY when user explicitly requests: security audit, vulnerability scan, or penetration test review. NOT for regular feature work."
+source: package
+---
+
+# security-audit
+
+## Mission
+
+Find real security vulnerabilities in code before they are exploited. This skill is
+**proactive** — it audits code for security weaknesses, not just responds to incidents.
+
+For writing secure code patterns (policies, auth, CSRF), use the `security` skill instead.
+
+## When to use
+
+Use this skill when:
+
+- Auditing a codebase or module for security risks
+- `analysis-autonomous-mode` routes here after detecting risky patterns
+- Reviewing code that handles user input, authentication, or authorization
+- Checking for vulnerabilities before a release or deployment
+
+Do NOT use when:
+
+- Writing new auth/policy code → use `security`
+- Hunting for functional bugs → use `bug-analyzer` (proactive mode)
+- Investigating performance → use `performance-analysis`
+
+## Procedure: Security audit
+
+### 1. Map attack surface
+
+Identify all entry points where untrusted data enters:
+
+- HTTP request parameters, headers, cookies
+- File uploads
+- API payloads (JSON, XML, form data)
+- Webhook callbacks
+- Queue job payloads from external sources
+- Import files (CSV, Excel, XML)
+- URL path segments and query strings
+
+### 2. Trace trust boundaries
+
+For each entry point, trace where user input flows:
+
+```
+User Input → Controller → Validation → Service → DB/File/External
+                 ↓              ↓           ↓
+            Is it sanitized?  Complete?  Used safely?
+```
+
+### 3. Check vulnerability categories
+
+| Category | What to look for |
+|---|---|
+| **SQL Injection** | Raw queries with concatenation, missing parameter binding |
+| **XSS** | Unescaped output in Blade (`{!! !!}`), JSON responses with HTML |
+| **CSRF** | Missing middleware, API endpoints without token verification |
+| **Auth bypass** | Missing policy checks, broken gate logic, `withoutMiddleware()` |
+| **IDOR** | Direct object access without ownership verification |
+| **Mass assignment** | Missing `$fillable`/`$guarded`, `request()->all()` in create/update |
+| **File upload** | Missing type validation, path traversal, executable uploads |
+| **SSRF** | User-controlled URLs passed to HTTP client |
+| **Deserialization** | Unserializing user input, unsafe queue payloads |
+| **Secret exposure** | Hardcoded credentials, secrets in logs, `.env` in public dir |
+| **Rate limiting** | Missing throttle on auth endpoints, password reset, API |
+| **Header injection** | User input in response headers, email headers |
+
+### 4. Framework-specific checks
+
+**Laravel:**
+- `env()` in non-config files (leaks in debug mode)
+- Debug mode (`APP_DEBUG=true`) in production
+- Missing `$fillable` on models used with `request()->all()`
+- `Route::any()` exposing unintended HTTP methods
+- Missing rate limiting on login/register/password-reset
+- Broadcast channels without proper authorization
+- Missing encryption on sensitive cookie/session data
+
+### 5. Dependency audit
+
+- Check `composer.lock` for known vulnerable packages
+- Check `package-lock.json` for frontend vulnerabilities
+- Identify outdated packages with known CVEs
+- Check if security patches are available
+
+## Output format
+
+For each vulnerability:
+
+- **Vulnerability:** concise title
+- **Category:** OWASP category (Injection, Broken Auth, etc.)
+- **Location:** file and line
+- **Severity:** Low / Medium / High / Critical
+- **Exploitability:** How easy to exploit (trivial / requires auth / complex)
+- **Impact:** What an attacker could achieve
+- **Evidence:** code reference showing the weakness
+- **Fix:** concrete mitigation
+- **Confidence:** Low / Medium / High
+
+## Integration with other skills
+
+- **analysis-autonomous-mode** — routes here when security concerns are detected
+- **security** — complementary: security is about writing secure code, this is about finding holes
+- **universal-project-analysis** — provides context about packages and framework usage
+- **bug-analyzer** — some bugs have security implications (chain when found)
+
+## Gotcha
+
+- Don't report theoretical vulnerabilities without a concrete attack vector — false positives erode trust.
+- The model tends to flag framework-handled security as issues (e.g., Laravel's CSRF is already handled).
+- Always check if a finding is already mitigated by middleware or configuration before reporting it.
+
+## Do NOT
+
+- Do NOT report theoretical risks that require impossible preconditions
+- Do NOT ignore user input flows — always trace from entry to usage
+- Do NOT assume frameworks handle everything — verify middleware and config
+- Do NOT confuse code quality issues with security vulnerabilities
+- Do NOT skip dependency checking — known CVEs are real risks

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

@@ -0,0 +1,170 @@
+---
+name: sentry-integration
+description: "Use when the user shares a Sentry URL, says "check Sentry", or wants to investigate production errors. Uses Sentry MCP tools for deep analysis."
+source: package
+---
+
+# Sentry Skill
+
+## When to use
+
+Use this skill when:
+- Investigating a Sentry error or issue URL
+- Analyzing error patterns, frequency, or affected users
+- Working with Sentry MCP tools for issue details
+- Adding error reporting or breadcrumbs to code
+- Configuring Sentry alerts or release tracking
+
+## Available MCP tools
+
+### Issue investigation
+
+| Tool | Purpose |
+|---|---|
+| `get_issue_details` | Full issue details: stacktrace, tags, metadata |
+| `get_issue_tag_values` | Distribution by tag (browser, URL, environment, user) |
+| `search_issues` | Find issues by criteria (unresolved, critical, etc.) |
+| `search_events` | Count/aggregate events, find individual error logs |
+| `search_issue_events` | Filter events within a specific issue |
+| `analyze_issue_with_seer` | AI root cause analysis with code fix suggestions |
+
+### Context tools
+
+| Tool | Purpose |
+|---|---|
+| `get_trace_details` | Trace overview for performance issues |
+| `get_event_attachment` | Download screenshots, logs attached to events |
+| `find_organizations` | Find org slug (needed for most queries) |
+| `find_projects` | Find project slug |
+| `find_releases` | Check recent releases and deploy timing |
+
+## Procedure: Investigate a Sentry error
+
+### 1. Get issue details
+
+From a Sentry URL:
+```
+get_issue_details(issueUrl='https://sentry.io/issues/PROJECT-123/')
+```
+
+From an issue ID:
+```
+get_issue_details(organizationSlug='my-org', issueId='PROJECT-123')
+```
+
+### 2. Analyze the stacktrace
+
+- **Top frame** = where it crashed
+- **Bottom frame** = entry point (HTTP request, job, command)
+- Read each file in the call chain using `codebase-retrieval`
+- Identify where data becomes invalid or assumptions break
+
+### 3. Check distribution
+
+```
+get_issue_tag_values(issueId='PROJECT-123', tagKey='environment')
+get_issue_tag_values(issueId='PROJECT-123', tagKey='url')
+get_issue_tag_values(issueId='PROJECT-123', tagKey='browser')
+```
+
+Useful tags: `environment`, `url`, `browser`, `os`, `release`, `user`, `device`
+
+### 4. Check frequency and timing
+
+```
+search_events(organizationSlug='my-org', naturalLanguageQuery='count of errors for PROJECT-123 in last 7 days')
+```
+
+### 5. AI analysis (if needed)
+
+```
+analyze_issue_with_seer(issueUrl='https://sentry.io/issues/PROJECT-123/')
+```
+
+Only use when you cannot determine the root cause from the stacktrace alone.
+
+## Error reporting in code
+
+### MonitoringHelper (project convention)
+
+Always use the project's `MonitoringHelper` — never the Sentry SDK directly:
+
+```php
+// ✅ Correct
+MonitoringHelper::captureException($exception);
+
+// ❌ Wrong
+\Sentry\captureException($exception);
+```
+
+### Breadcrumbs
+
+Use project enums for structured breadcrumbs:
+
+```php
+use App\Enums\Sentry\BreadcrumbType;
+use App\Enums\Sentry\BreadcrumbLevel;
+```
+
+### Context
+
+Check the project for Sentry context enums and the tenant switching service that sets context automatically.
+
+## Common error patterns
+
+| Pattern | Root cause | Fix approach |
+|---|---|---|
+| `TypeError: null passed to non-nullable` | Missing null check on optional DB column | Add null guard or make parameter nullable |
+| `ModelNotFoundException` | Deleted or missing related record | Add `optional()` or existence check |
+| `ConnectionException` | Multi-tenant DB switch failed | Check tenant switching service flow |
+| `ValidationException` in jobs | Job data changed between dispatch and execution | Re-validate in `handle()` |
+| `Undefined array key` | External API/import data missing expected field | Add `array_key_exists()` or null coalescing |
+
+## Search patterns
+
+### Find issues by criteria
+
+```
+search_issues(organizationSlug='my-org', naturalLanguageQuery='unresolved errors in production last 24h')
+search_issues(organizationSlug='my-org', naturalLanguageQuery='errors affecting more than 100 users')
+search_issues(organizationSlug='my-org', naturalLanguageQuery='issues assigned to me')
+```
+
+### Count events
+
+```
+search_events(organizationSlug='my-org', naturalLanguageQuery='how many errors today')
+search_events(organizationSlug='my-org', naturalLanguageQuery='count of database failures this week')
+```
+
+## Related
+
+- **Skill:** `logging-monitoring` — full monitoring stack (Sentry + Grafana + Loki)
+- **Skill:** `bug-analyzer` — uses Sentry as input for bug investigation
+- **Command:** `/bug-investigate` — fetches Sentry details automatically
+- **Config:** `config/sentry.php` — Sentry DSN and configuration
+
+
+## Output format
+
+1. Sentry integration code with proper context and breadcrumbs
+2. Error grouping configuration if needed
+
+## Gotcha
+
+- Sentry groups errors by stacktrace — different root causes may appear as the same issue. Check multiple events.
+- The model tends to analyze only the latest event — check the "Events" tab for patterns across time.
+- Don't use Sentry MCP tools for simple lookups — use the Sentry web UI link instead (saves tokens).
+
+## Do NOT
+
+- Do NOT use Sentry SDK directly — use MonitoringHelper.
+- Do NOT ignore Sentry errors without investigating root cause.
+- Do NOT expose sensitive data in Sentry error context.
+
+## Auto-trigger keywords
+
+- Sentry
+- error tracking
+- issue investigation
+- error reporting

package/.agent-src/skills/sequential-thinking/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: sequential-thinking
+description: "ONLY when user explicitly requests: step-by-step reasoning, structured problem decomposition, or iterative analysis. NOT for regular coding tasks."
+source: package
+---
+
+# sequential-thinking
+
+## When to use
+
+Use this skill when:
+- A problem requires multiple interconnected reasoning steps
+- The initial scope or approach is uncertain
+- You need to filter through complexity to find core issues
+- You may need to backtrack or revise earlier conclusions
+- You want to explore alternative solution paths
+- A decision has significant consequences and needs careful analysis
+
+Do NOT use for:
+- Simple queries with direct answers
+- Single-step tasks
+- Well-understood, routine operations
+
+## Core capabilities
+
+### Iterative reasoning
+
+Break complex problems into sequential thought steps. Each step builds on previous ones
+but can also question or revise them.
+
+### Dynamic scope
+
+Start with an estimate of needed steps, but adjust as understanding evolves.
+Don't commit to a fixed plan — let the analysis guide the depth.
+
+### Revision tracking
+
+When new information contradicts an earlier conclusion:
+1. **Acknowledge** the contradiction explicitly.
+2. **Identify** which earlier step needs revision.
+3. **Revise** the conclusion with the new evidence.
+4. **Propagate** the change to all dependent steps.
+
+### Branch exploration
+
+When multiple approaches seem viable:
+1. **Identify** the decision point.
+2. **Explore** each branch briefly (2-3 steps).
+3. **Compare** outcomes and tradeoffs.
+4. **Choose** the best path with reasoning.
+5. **Document** why alternatives were rejected.
+
+## Procedure: Sequential thinking
+
+### Step 1: Frame the problem
+
+- What exactly needs to be solved?
+- What are the constraints?
+- What does success look like?
+- What information is missing?
+
+### Step 2: Decompose
+
+- Break into independent sub-problems where possible.
+- Identify dependencies between sub-problems.
+- Order by dependency (solve prerequisites first).
+
+### Step 3: Solve iteratively
+
+For each sub-problem:
+1. **Analyze** — What do we know? What do we need?
+2. **Hypothesize** — What's the most likely solution?
+3. **Verify** — Does the hypothesis hold against evidence?
+4. **Conclude** or **Revise** — Accept or go back to step 1.
+
+### Step 4: Synthesize
+
+- Combine sub-problem solutions into the overall answer.
+- Check for contradictions between sub-solutions.
+- Verify the combined solution against the original problem.
+
+### Step 5: Validate
+
+- Does the solution actually solve the stated problem?
+- Are there edge cases not covered?
+- Is the solution proportional to the problem (not over-engineered)?
+
+## When to revise
+
+Revise earlier thinking when:
+- New evidence contradicts a previous assumption.
+- A sub-problem solution doesn't fit the overall picture.
+- The user provides new information that changes the context.
+- You realize you were solving the wrong problem.
+
+## When to branch
+
+Explore alternatives when:
+- Two approaches seem equally viable.
+- The stakes are high (architecture decisions, data migrations).
+- The user asks "what if we did X instead?"
+- The first approach hits a dead end.
+
+## Integration with other skills
+
+- **bug-analyzer** — Use sequential thinking for complex root cause analysis.
+- **feature-planning** — Use for architecture decision exploration (Phase 4).
+- **technical-specification** — Use for evaluating alternatives in specs.
+- **refactorer** — Use for planning multi-step refactoring safely.
+
+## Anti-patterns
+
+| Anti-pattern | Problem | Fix |
+|---|---|---|
+| **Premature conclusion** | Jumping to a solution without analysis | Complete at least Steps 1-3 first |
+| **Analysis paralysis** | Endless exploration without deciding | Set a step limit, then decide |
+| **Ignoring contradictions** | Pushing forward despite conflicting evidence | Stop and revise |
+| **Linear-only thinking** | Never considering alternatives | Branch at key decision points |
+| **Scope creep** | Problem keeps expanding during analysis | Re-frame and constrain |
+
+
+## Output format
+
+1. Numbered reasoning steps with conclusions
+2. Final answer or recommendation with confidence level
+
+## Auto-trigger keywords
+
+- problem solving
+- step-by-step
+- reasoning
+- decomposition
+
+## Gotcha
+
+- Don't use sequential thinking for simple tasks — it adds latency without value.
+- The model tends to generate too many thoughts — cap at 10 unless the problem truly needs more.
+- Each thought should build on the previous one — avoid restating the same point in different words.
+
+## Do NOT
+
+- Do NOT use this for simple, well-understood tasks — it adds unnecessary overhead.
+- Do NOT call `sequentialthinking` more than **once per task**. If you're calling it repeatedly,
+  you're looping — stop and act directly instead.
+- Do NOT use `sequentialthinking` as a "thinking proxy" — if the task is "view a file" or
+  "run a command", just do it. No thinking step needed.
+- Do NOT skip the validation step — always check the solution against the original problem.
+- Do NOT ignore contradictions — they are signals, not noise.
+- Do NOT commit to a fixed number of steps upfront — let the problem guide the depth.
+
+## References
+
+- **Chain-of-Thought (CoT)** — [arxiv.org/abs/2201.11903](https://arxiv.org/abs/2201.11903)
+  Step-by-step reasoning improves complex problem solving in large
+  language models. This skill constrains CoT by capping the number
+  of thoughts and enforcing a validation step — avoids the common
+  failure mode of unbounded chain expansion.
+