@event4u/agent-config 1.9.1

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

@@ -0,0 +1,234 @@
+---
+name: agent-docs-writing
+description: "Use when reading, creating, or updating agent documentation, module docs, roadmaps, or AGENTS.md. Understands the full .augment/, agents/, and copilot-instructions structure."
+source: package
+---
+
+# agent-docs
+
+## When to use
+
+Use this skill when:
+- Navigating the documentation structure to find relevant information
+- Creating or updating agent documentation after changes
+- Setting up documentation for a new module or package
+- Understanding what documentation exists and where
+
+Do NOT use when:
+- Creating code or making technical changes (use coding skills)
+- Looking for coding guidelines (use `guidelines` skill)
+
+## Documentation hierarchy
+
+The documentation is organized in layers, from cross-project to module-specific:
+
+### Layer 1: `.augment/` — Cross-project (identical in all repos)
+
+```
+.augment/
+├── rules/          ← Always-active rules (coding, docker, scope, language, etc.)
+├── commands/       ← Slash commands (fix-ci, create-pr, quality-fix, etc.)
+├── skills/         ← Reusable skill definitions (coder, code-refactoring, etc.)
+├── contexts/       ← Shared contexts about the agent system itself
+├── templates/      ← Templates for features, roadmaps, contexts
+└── guidelines/     ← Coding guidelines by language
+    └── php/        ← PHP guidelines (controllers, eloquent, patterns, etc.)
+```
+
+**Purpose:** Universal agent behavior that applies to ALL projects and packages.
+**Language:** English.
+**Key rule:** This directory is **identical** across repos. Never add project-specific content here.
+**Templates** are the single source of truth for document structure — never store templates in `agents/`.
+
+### Layer 2: `AGENTS.md` — Project-level entry point
+
+Located in the project root. Contains:
+- Project description and tech stack
+- Development setup (Docker, env files, Makefile targets)
+- Testing conventions
+- Quality tool configuration
+- Links to `./agents/` for detailed docs
+
+**Purpose:** First file an agent reads. Provides the full project context.
+**Not every project has this** — packages may only have `./agents/`.
+
+### Layer 3: `.github/copilot-instructions.md` — Coding standards
+
+Located in `.github/`. Contains:
+- Architecture rules
+- PHP coding standards
+- Naming conventions
+- Eloquent & database rules
+- API development rules
+
+**Purpose:** Coding standards shared with GitHub Copilot and other AI tools.
+**Not every project has this** — check if it exists before referencing it.
+
+### Layer 4: `agents/overrides/` — Project-level overrides
+
+```
+agents/overrides/
+├── rules/           ← Override .augment/rules/*.md
+├── skills/          ← Override .augment/skills/*/SKILL.md
+├── commands/        ← Override .augment/commands/*.md
+├── guidelines/      ← Override .augment/guidelines/**/*.md
+└── templates/       ← Override .augment/templates/*.md
+```
+
+**Purpose:** Project-specific customizations of shared `.augment/` resources (which are delivered as a package).
+**Mechanism:** Each override file has a `Mode` header — `extend` (additive) or `replace` (full swap).
+**Key rule:** Never modify `.augment/` directly — always use overrides for project-specific needs.
+**See:** `.augment/contexts/override-system.md` for naming conventions and format.
+
+### Layer 5: `./agents/` — Project-specific documentation
+
+```
+agents/
+├── database-setup.md       ← DB architecture, connections, tenancy
+├── testing.md              ← Test suites, conventions, seeders
+├── dto.md                  ← DTO patterns and base classes
+├── services-and-repos.md   ← Service layer conventions
+├── overrides/              ← Project-level overrides (see Layer 4)
+├── features/               ← Feature plans (project-wide)
+│   └── {feature-name}.md
+├── roadmaps/               ← Multi-step change plans
+│   └── {roadmap-name}.md
+│   └── current.md
+└── contexts/               ← Context documents (codebase area snapshots)
+    └── {context-name}.md
+```
+
+**Purpose:** Project-specific architecture, conventions, and domain knowledge.
+**Structure rule:** Structural docs directly in `agents/`, features/roadmaps in subdirectories.
+**Templates** live in `.augment/templates/`, NOT in `agents/` subdirectories.
+
+### Layer 6: `app/Modules/*/agents/` — Module-specific documentation
+
+```
+app/Modules/ClientSoftware/
+├── agents/
+│   ├── module-description.md
+│   ├── features/               ← Module-scoped feature plans
+│   │   └── {feature-name}.md
+│   ├── roadmaps/               ← Module-scoped roadmaps
+│   │   └── {roadmap-name}.md
+│   └── contexts/               ← Module-scoped context documents
+│       └── {context-name}.md
+└── Docs/
+    └── technical-docs.md
+```
+
+**Purpose:** Documentation scoped to a specific module.
+**When to create:** When a module has its own conventions, complex domain logic, or active roadmaps.
+
+### Layer 7: `Docs/` — Technical documentation
+
+```
+Docs/                           ← Project-level technical docs
+app/Modules/*/Docs/             ← Module-level technical docs
+```
+
+**Purpose:** Technical documentation for humans (setup guides, architecture diagrams, API docs).
+**Difference from `agents/`:** `Docs/` is for human readers, `agents/` is optimized for AI agents.
+
+### Layer 8: Package documentation
+
+```
+{package-root}/
+├── agents/
+│   ├── package-description.md
+│   └── roadmaps/
+└── AGENTS.md (optional)
+```
+
+**Purpose:** Same structure as projects, but for Composer packages.
+
+## Reading order
+
+When starting work, read documentation in this order:
+
+1. `AGENTS.md` (if it exists) — project overview
+2. `.github/copilot-instructions.md` (if it exists) — coding standards
+4. `agents/overrides/` — check for project-level overrides of skills/rules/commands
+5. `./agents/` — project-specific docs relevant to the task
+6. `app/Modules/{Module}/agents/` — if working on a module
+7. `agents/features/` or module `agents/features/` — if related feature plan exists
+8. `agents/roadmaps/` or module `agents/roadmaps/` — if continuing existing work
+
+## Procedure: Create or update agent docs
+
+1. **Identify trigger** — What changed? (see table below)
+2. **Locate target** — Find the correct file in the documentation hierarchy.
+3. **Update content** — Edit or create the doc. English only in `.md` files.
+4. **Verify** — Confirm the doc is consistent with surrounding files and cross-references are valid.
+
+| Trigger | Action |
+|---|---|
+| New module created | Create `app/Modules/{Module}/agents/` with module description |
+| Significant multi-step change | Ask user about creating a roadmap in `agents/roadmaps/` |
+| New convention introduced | Update relevant doc in `./agents/` or `.augment/guidelines/` |
+| Database schema changed | Update `agents/docs/database-setup.md` |
+
+## When to update documentation
+
+After making changes, check if docs need updating:
+
+- **Roadmap step completed** → mark `[x]` in the roadmap file
+- **Structural changes** → update affected docs in `./agents/`
+- **New patterns** → update or create guideline docs
+
+## Doc sync check (after code changes)
+
+After completing a significant code change, run this mental checklist:
+
+| What changed | Doc to check |
+|---|---|
+| Database schema (migration) | `agents/docs/database-setup.md` |
+| New API endpoint | OpenAPI annotations, `AGENTS.md` API section |
+| New module created | Create `app/Modules/{Module}/agents/` |
+| Service/repository signature changed | Check if referenced in `agents/docs/services-and-repos.md` |
+| New environment variable | `.env.example`, `AGENTS.md` environment section |
+| Docker/compose change | `agents/docs/docker.md`, `Makefile` documentation |
+| New Artisan command | `AGENTS.md` commands section |
+| New pattern/convention introduced | Relevant guideline in `.augment/guidelines/` |
+
+**When unsure** — ask with numbered options:
+```
+> 1. Yes — update the docs
+> 2. No — leave as-is
+```
+
+Do NOT auto-update docs without the user's knowledge. Flag what needs updating and let the user decide.
+
+## Rules
+
+- All `.md` files must be in **English**.
+- Do NOT create docs unless there's a real need.
+- Do NOT duplicate content that's already in `AGENTS.md` or `.github/copilot-instructions.md`.
+- Do NOT write docs just to document what you did — only document things others need to know.
+- If unsure whether a doc needs updating, **ask the user**.
+
+## Output format
+
+1. Created or updated documentation file(s) in the correct location
+2. Summary of what changed and why
+
+## Gotcha
+
+- Don't create documentation files unless explicitly requested — the scope-control rule overrides this skill.
+- Always check if a doc already exists before creating a new one — duplicates are worse than gaps.
+- AGENTS.md and copilot-instructions.md have different audiences — don't copy content between them.
+- Module docs go in `app/Modules/*/agents/`, NOT in the central `agents/` directory.
+
+## Do NOT
+
+- Do NOT create docs unless there's a real need (new module, significant change).
+- Do NOT duplicate information already in AGENTS.md or copilot-instructions.md.
+- Do NOT write docs just to document what you did — only document things others need to know.
+
+## Auto-trigger keywords
+
+- agent documentation
+- docs structure
+- when to read docs
+- documentation maintenance

package/.agent-src/skills/analysis-autonomous-mode/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: analysis-autonomous-mode
+description: "ONLY when user explicitly requests autonomous analysis, deep investigation, multi-step research, or 'dig into this end-to-end without asking me each step' — NOT for normal feature work."
+source: package
+---
+
+# analysis-autonomous-mode
+
+## Mission
+
+Act as an autonomous engineering system that coordinates specialist analysis skills.
+
+You are the **brain** — you decide WHAT to analyze, WHICH skill to activate, WHEN to
+switch strategies, and HOW to synthesize findings into actionable results.
+
+You do NOT perform deep analysis yourself. You route to specialists and merge their output.
+
+## When to use
+
+Use this skill when:
+
+- A broad investigation is needed and the right analysis path is unclear
+- Multiple problem classes may be involved (bugs + performance + security)
+- The user asks for a full project audit or deep investigation
+- You need to coordinate multiple analysis passes without duplication
+
+Do NOT use when:
+
+- Only one narrow skill is clearly needed (use it directly)
+- A small isolated code change with fully known context
+- Writing code, tests, or documentation (use the appropriate skill)
+
+## Routing
+
+**Always use `analysis-skill-router` first** to decide which analysis skill handles the request.
+
+The router selects by scope, framework, and problem shape. Key routes:
+
+| Scope | Route to |
+|---|---|
+| Unknown system / full audit | `universal-project-analysis` |
+| Discovery-focused | `project-analysis-core` |
+| Root-cause / multi-hypothesis | `project-analysis-hypothesis-driven` |
+| Laravel | `project-analysis-laravel` |
+| Symfony | `project-analysis-symfony` |
+| Zend/Laminas | `project-analysis-zend-laminas` |
+| Node/Express | `project-analysis-node-express` |
+| React | `project-analysis-react` |
+| Next.js | `project-analysis-nextjs` |
+| Bug-focused | `bug-analyzer` |
+| Performance bottleneck | `performance-analysis` |
+| Security concern | `security-audit` |
+| Documentation | `project-analyzer` |
+
+**Rule:** Route to the narrowest matching skill. Do NOT default to `universal-project-analysis`.
+
+### Phase 2 — Establish context before specializing
+
+Before activating any specialist:
+
+1. Detect stack and framework
+2. Detect exact versions (`composer.lock`, `package-lock.json`)
+3. Identify key packages
+4. Identify entrypoints and affected flow
+5. Read project docs (`AGENTS.md`, `agents/`, module docs)
+6. If no obvious README → search for `.md` files (`find . -name "*.md" -maxdepth 3`) — docs are sometimes hidden in non-standard locations
+
+Never send a specialist in blind.
+
+### Phase 3 — Activate specialist(s)
+
+Route to the primary skill. Monitor findings for signals to chain additional skills:
+
+- Bug found during performance analysis → chain `bug-analyzer`
+- Package misuse found during bug hunting → chain `universal-project-analysis`
+- Auth weakness found during code review → chain `security-audit`
+- N+1 query found during bug analysis → chain `performance-analysis`
+
+### Phase 4 — Synthesize findings
+
+Merge all specialist findings into ONE prioritized output:
+
+1. Confirmed root causes (with evidence)
+2. Contributing factors
+3. Risks not yet proven but worth checking
+4. Concrete fixes (ordered by priority)
+5. Recommended next steps
+
+Never dump isolated observations without synthesis.
+
+## Procedure: Autonomous investigation loop
+
+When running a broad investigation, repeat until confident:
+
+```
+1. Assess current understanding
+2. Identify biggest unknown
+3. Choose specialist skill to fill that gap
+4. Execute analysis
+5. Evaluate result — did it answer the question?
+6. Update mental model
+7. Decide: narrow down or broaden scope?
+8. If confident → synthesize and present
+   If not → loop back to step 2
+```
+
+## Adaptation rules
+
+| Signal | Action |
+|---|---|
+| Hypothesis fails | Pivot — try alternative explanation |
+| New evidence appears | Re-evaluate all conclusions |
+| Stuck in one skill | Broaden — switch to `universal-project-analysis` |
+| Clear pattern recognized | Narrow — go deep with the right specialist |
+| 3 failed attempts | Stop — summarize state, ask user for direction |
+
+## Learning from past analyses
+
+After completing an investigation, extract reusable patterns:
+
+- **Root cause type** — classify (config issue, version mismatch, package misuse, async bug, etc.)
+- **Detection signal** — what symptom led to the root cause?
+- **Framework-specific** — is this a known pattern for this framework version?
+
+When starting a NEW investigation, compare against known patterns:
+
+- If similar symptoms → suggest likely root cause early
+- If same framework + version → check known pitfalls first
+- If same package → check changelog and known issues first
+
+This accelerates future investigations and reduces repeated mistakes.
+
+## Escalation rules
+
+**Narrow → Broad** when:
+
+- Focused path cannot explain the symptom
+- Framework/package assumptions are unverified
+- Issue spans architecture boundaries
+- Evidence suggests multiple interacting causes
+
+**Broad → Narrow** when:
+
+- Enough context exists to test a focused hypothesis
+- Symptoms clearly point to one problem class
+- Code and docs reveal likely failure mechanism
+
+## Conflict resolution
+
+When specialist findings conflict:
+
+1. Trust direct code evidence over assumptions
+2. Trust version-specific official docs over memory
+3. Trust reproducible execution logic over generic best practices
+4. Separate confirmed facts from plausible hypotheses
+5. Explicitly mark uncertainty instead of forcing a conclusion
+
+## Output format
+
+### Investigation Summary
+- What was analyzed, which skills were used, why
+
+### System Context
+- Stack, framework + version, key packages, affected flow
+
+### Confirmed Findings
+For each finding: Issue / Severity / Root Cause / Evidence / Fix / Confidence
+
+### Contributing Risks
+Plausible but not fully confirmed concerns.
+
+### Recommended Fix Order
+Prioritized by: production impact → exploitability → user-facing breakage → effort vs value
+
+## Gotcha
+
+- Don't run autonomously for more than 10 steps without checking in with the user.
+- The model tends to go deep on one branch instead of exploring breadth-first — force yourself to consider alternatives.
+- Save intermediate findings — if the context resets, all analysis is lost.
+
+## Do NOT
+
+- Do NOT perform deep analysis yourself — route to specialists
+- Do NOT run every skill by default without a reason
+- Do NOT stay in one skill when evidence points elsewhere
+- Do NOT mix confirmed findings with guesses
+- Do NOT output fragmented observations without synthesis
+- Do NOT follow a fixed workflow blindly — adapt to what you learn
+- Do NOT stop after the first explanation — verify it
+
+## References
+
+- **Self-Refine** — [arxiv.org/abs/2303.17651](https://arxiv.org/abs/2303.17651)
+  Iterative self-improvement through self-generated feedback. This
+  skill adapts the pattern by routing the critique step to domain
+  specialists instead of a monolithic self-critique.
+

package/.agent-src/skills/analysis-skill-router/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: analysis-skill-router
+description: "Use when picking which analysis or project-analysis-* skill fits a request — routes by scope, framework, and symptom — even if the user just says 'analyze this' or 'dig into the codebase'."
+source: package
+---
+
+# analysis-skill-router
+
+## When to use
+
+Use this skill when:
+
+* A request may need deep analysis
+* It is unclear which analysis skill should be used
+* Multiple analysis skills could plausibly apply
+* The stack/framework is known but the correct analysis path is unclear
+* `analysis-autonomous-mode` needs a routing decision
+
+Do NOT use when:
+
+* The correct specialist skill is already obvious
+* The task is not an analysis task
+* The task is normal implementation work without investigation needs
+
+## Procedure
+
+### 1. Identify request scope
+
+Classify the request as one of:
+
+* full project analysis
+* architecture review
+* broad multi-layer debugging
+* framework-specific deep analysis
+* narrow root-cause analysis
+* performance/security specialist analysis
+* simple local code issue
+
+### 2. Check whether deep analysis is justified
+
+Use deep analysis only if at least one is true:
+
+* the user explicitly asks for broad analysis
+* the system is unclear or unknown
+* the issue spans multiple layers
+* architecture reconstruction is required
+* the cause is not local and not obvious
+
+If none apply → do NOT route to a broad analysis skill.
+
+### 3. Detect framework or system type
+
+Check whether the request clearly targets:
+
+* Laravel, Symfony, Zend/Laminas, Node/Express, React, Next.js
+* unknown / mixed stack
+
+### 4. Route to the correct skill
+
+#### Broad / unknown system
+
+* full project analysis or unclear stack → `universal-project-analysis`
+* unknown system, discovery-focused → `project-analysis-core`
+
+#### Root-cause analysis
+
+* concrete multi-cause problem → `project-analysis-hypothesis-driven`
+* bug-focused but not full-project → `bug-analyzer`
+
+#### Backend framework analysis
+
+* Laravel → `project-analysis-laravel`
+* Symfony → `project-analysis-symfony`
+* Zend/Laminas → `project-analysis-zend-laminas`
+* Node/Express → `project-analysis-node-express`
+
+#### Frontend / rendering analysis
+
+* React state/render/hooks issues → `project-analysis-react`
+* Next.js SSR/client/cache/hydration issues → `project-analysis-nextjs`
+
+#### Specialist follow-up routing
+
+* performance bottleneck → `performance-analysis`
+* security concern → `security-audit`
+
+### 5. Validate routing quality
+
+Check:
+
+* the chosen skill is narrower than the broadest possible option
+* full-project analysis is actually justified if selected
+* framework-specific skill matches the explicit framework
+* no simpler specialist skill was skipped
+
+## Output format
+
+1. Selected skill
+2. Reason for selection
+3. Why broader alternatives were not chosen
+4. Optional chained specialist skills
+
+## Routing heuristics
+
+**Choose `universal-project-analysis` only if:** user explicitly wants full audit, architecture must be reconstructed, stack is unclear, multiple subsystems involved.
+
+**Choose `project-analysis-core` if:** broad discovery needed, framework deep-dive not yet justified.
+
+**Choose `project-analysis-hypothesis-driven` if:** problem is concrete, multiple causes plausible, main job is explanation not discovery.
+
+**Choose framework-specific analysis if:** framework is explicit, failure pattern is framework-shaped.
+
+**Do NOT route broadly if:** one component or file is enough, fix is obvious and local, task is implementation not investigation.
+
+## Examples
+
+**"Analyze this whole Laravel project"** → `universal-project-analysis` → chain `project-analysis-laravel`
+**"Hydration mismatch in Next.js"** → `project-analysis-nextjs` (no full-project needed)
+**"Bug could be cache, queue, or version mismatch"** → `project-analysis-hypothesis-driven`
+**"Change one React component"** → no analysis skill, use implementation skill
+
+## Gotcha
+
+* The most expensive skill is often not the best skill.
+* Broad analysis feels safe but reduces sharpness when the problem is already localized.
+* Framework-specific routing should happen as early as possible once the framework is explicit.
+
+## Do NOT
+
+* Do NOT default to `universal-project-analysis`
+* Do NOT use full-project analysis for normal feature work
+* Do NOT choose a generic skill when a framework-specific one clearly fits
+* Do NOT route to deep analysis when a simple specialist skill is enough
+* Do NOT confuse discovery with root-cause investigation

package/.agent-src/skills/api-design/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: api-design
+description: "Use when designing APIs, planning endpoints, REST conventions, versioning, or deprecation — even when the user just says 'expose this as an endpoint' without naming API design."
+source: package
+---
+
+# api-design
+
+## When to use
+
+Use this skill when designing new API endpoints, restructuring existing APIs, or deciding about versioning and deprecation.
+
+Do NOT use when:
+- Implementing an already-designed endpoint (use `api-endpoint` skill)
+- Writing tests for APIs (use `api-testing` skill)
+
+## Procedure: Design an API
+
+1. **Gather context** — read `agents/contexts/api-versioning.md`, `agents/docs/api-resources.md`, `agents/docs/query-filter.md`, `agents/docs/controller.md`, and guideline `php/api-design.md`.
+2. **Identify the resource** — determine the domain entity, its attributes, and relationships. Check existing models and resources for field naming patterns.
+3. **Define endpoints** — list each endpoint with HTTP method, URL path, request body, query parameters, and response structure. Follow existing route file patterns.
+4. **Decide versioning** — determine whether this extends the current version or requires a new version (see decision table below).
+5. **Design error responses** — define 4xx/5xx responses matching the project's existing error format.
+6. **Validate against existing patterns** — compare your design with 2-3 similar existing endpoints. Flag any inconsistencies.
+7. **Run adversarial review** — use `adversarial-review` skill to check for breaking changes, consistency issues, and missing error cases.
+
+## Versioning decisions
+
+### URL-based versioning
+
+Routes versioned via URL prefix: `/api/v1/...`, `/api/v2/...`
+
+```
+routes/api/v1/projects.php  → /api/v1/projects
+routes/api/v2/projects.php  → /api/v2/projects
+```
+
+### Automatic fallback
+
+If a route doesn't exist in the requested version, the system falls back to the next older version. Configured in `config/app.php`:
+
+```php
+'api_versioning' => [
+    'versions' => 'v2,v1',  // newest first
+],
+```
+
+### When to create a new version
+
+| Change type | Action |
+|---|---|
+| Add optional field | Extend current version |
+| Add new endpoint | Add to current version |
+| Remove/rename field | New version |
+| Change field type | New version |
+| Change validation rules | New version |
+
+> If an existing client would break without code changes → **new version required**.
+
+### Deprecation workflow
+
+1. **Mark as deprecated** — add headers: `Deprecation: true`, `Sunset: YYYY-MM-DD`, `Link: <successor>`
+2. **Document** — add to API changelog with sunset date
+3. **Monitor usage** — track clients still using deprecated endpoints
+4. **Remove** — after sunset date, remove route + controller + docs
+
+Minimum 3 months between deprecation and removal.
+
+## Design review
+
+Before presenting an API design, run the **`adversarial-review`** skill.
+Focus on: Breaking changes? Consistency? Error responses?
+
+## Output format
+
+1. Endpoint specification — method, path, request/response structure
+2. Versioning decision with rationale
+3. Error response format following existing project patterns
+
+## Gotcha
+
+- Consistency beats "better" design — check existing patterns first.
+- Always include pagination on list endpoints.
+- Max nesting depth: 2 levels (`/users/{id}/orders/{id}`).
+- Don't version internal APIs only your own frontend consumes.
+- Deprecation without migration path is useless — always provide the replacement.
+- Don't duplicate controllers for new versions — use fallback logic.
+
+## Do NOT
+
+- Do NOT introduce a new response format in an established API — match existing patterns.
+- Do NOT create v2 endpoints without a deprecation plan for v1.
+- Do NOT skip pagination on list endpoints.
+
+## Auto-trigger keywords
+
+- API design
+- REST API
+- endpoint design
+- resource structure
+- response format
+- API versioning
+- deprecation
+- breaking changes