@event4u/agent-config 1.9.1

package/.agent-src/skills/project-analysis-core/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: project-analysis-core
+description: "Use for the universal deep-analysis workflow: project discovery, version resolution, docs loading, architecture mapping, execution flow, and package research."
+source: package
+---
+
+# project-analysis-core
+
+## When to use
+
+Use this skill when:
+
+* A project or codebase is unknown
+* You need a universal deep-analysis workflow
+* Framework-specific analysis is not yet clear
+* You need to reconstruct the real system before going deeper
+* `universal-project-analysis` routes here
+
+Do NOT use when:
+
+* The framework-specific path is already known and should be analyzed directly
+* The task is only a small local code question
+* The issue is already isolated and needs root-cause analysis more than discovery
+
+## Procedure
+
+### 1. Project discovery
+
+Identify: language, framework, runtime environment, package managers, entrypoints, documentation locations.
+
+Look at:
+
+* `composer.json`, `composer.lock`
+* `package.json`, lock files
+* bootstrap files
+* Dockerfile / compose files
+* CI workflows
+* README / AGENTS / docs
+
+### 2. Resolve exact versions
+
+Determine exact installed versions.
+
+Priority:
+
+1. lock files
+2. manifest constraints
+3. CI / Docker evidence
+4. framework constants or bootstrap evidence
+
+Validate: framework version is explicit, critical package versions are explicit, uncertainty is marked if no exact version is available.
+
+### 3. Load documentation
+
+For each important framework or package:
+
+* use version-matching docs
+* check official docs first
+* read upgrade notes if relevant
+* separate default behavior from project customizations
+
+### 4. Map architecture
+
+Build a system model:
+
+* entrypoints
+* dependency flow
+* container / DI structure
+* modules and boundaries
+* state systems
+* external integrations
+
+### 5. Map execution flow
+
+Trace the relevant path: HTTP, CLI, queue, scheduler, events, webhooks.
+
+Check:
+
+* where sync becomes async
+* where transactions start/end
+* where side effects happen
+* where external calls leave the system
+
+### 6. Analyze critical packages
+
+For each critical package:
+
+* where it is used
+* whether usage matches docs
+* whether config matches version
+* whether known issues exist
+* who depends on it
+
+### 7. Research real-world evidence
+
+Search for: exact errors, version-specific issues, known package bugs, unusual patterns.
+
+Prioritize:
+
+1. official docs
+2. vendor source
+3. GitHub issues
+4. verified StackOverflow answers
+5. blog posts last
+
+### 8. Validate the system model
+
+Check:
+
+* framework and package versions are explicit
+* architecture map matches code structure
+* execution path is traceable
+* docs were matched to actual versions
+* next-step specialist skill is clear
+
+## Output format
+
+1. Project summary
+2. Stack and versions
+3. Architecture map
+4. Execution flow overview
+5. Critical packages and findings
+6. Known uncertainties
+7. Recommended next specialist skill
+
+## Gotcha
+
+* If versions are guessed, the whole analysis becomes unreliable.
+* If you skip entrypoints, the architecture model will be shallow.
+* If you use latest docs instead of installed-version docs, conclusions may be wrong.
+
+## Do NOT
+
+* Do NOT assume framework or package versions
+* Do NOT stop after reading only manifests
+* Do NOT confuse project custom code with vendor behavior
+* Do NOT skip documentation lookup for critical packages
+* Do NOT conclude root cause here — route to hypothesis-driven analysis for that

package/.agent-src/skills/project-analysis-hypothesis-driven/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: project-analysis-hypothesis-driven
+description: "Use when a bug has multiple plausible causes across layers — competing hypotheses, validation loops, evidence-based conclusions — even when the user just says 'why is this happening?'."
+source: package
+---
+
+# project-analysis-hypothesis-driven
+
+## When to use
+
+Use this skill when:
+
+* There is a concrete issue to explain
+* Multiple root causes are plausible
+* The system spans several layers
+* A shallow single-explanation answer would be risky
+* `universal-project-analysis` or `bug-analyzer` routes here
+
+Do NOT use when:
+
+* You are still discovering the stack and architecture
+* The issue is already proven and only needs implementation
+* The request is a broad project overview without a specific problem focus
+
+## Core principles
+
+* Never stop at the first plausible explanation
+* Code, docs, and evidence beat intuition
+* Rejected hypotheses matter
+* Multiple interacting causes are common
+* Uncertainty must be marked explicitly
+
+## Procedure
+
+### 1. Define the observed problem
+
+State clearly: what happens, where it happens, when it happens, what was expected instead.
+
+Use concrete evidence: errors, stack traces, behavior differences, failing tests, logs.
+
+### 2. Build the hypothesis tree
+
+Generate multiple competing explanations.
+
+Typical categories:
+
+* config issue
+* version mismatch
+* package misuse
+* async/timing issue
+* data inconsistency
+* architecture flaw
+
+Do not stop at one explanation.
+
+### 3. Prioritize hypotheses
+
+Rank by: likelihood, impact, testability.
+Start with the most testable high-value explanation.
+
+### 4. Validate each hypothesis
+
+For each hypothesis:
+
+* check code
+* check docs
+* check runtime evidence
+* check real-world reports if relevant
+
+Mark: ✅ confirmed, ❌ rejected, ❓ uncertain.
+
+### 5. Check system interactions
+
+Look for cross-system causes:
+
+| System A | ↔ | System B | What can go wrong |
+|---|---|---|---|
+| Framework | ↔ | Package | Version mismatch, wrong lifecycle hook, config conflict |
+| Sync code | ↔ | Async code | Lost context, stale data, race conditions |
+| Config | ↔ | Runtime | Cached config doesn't match env |
+| Cache | ↔ | Database | Stale reads, inconsistent state after write |
+| Auth | ↔ | Middleware | Order-dependent behavior, missing guards |
+| Events | ↔ | Jobs | Events fire during seeding, serialization issues |
+| Transaction | ↔ | External calls | Side effects can't be rolled back |
+
+### 6. Perform reality check
+
+Ask:
+
+* does this fully explain the behavior?
+* what remains unexplained?
+* could multiple causes interact?
+* does contradictory evidence exist?
+
+If anything major remains unexplained: continue analysis, do not present a final conclusion yet.
+
+### 7. Validate conclusion quality
+
+Check:
+
+* at least 2 plausible hypotheses were considered where appropriate
+* rejected hypotheses are documented
+* conclusion is backed by code/doc/runtime evidence
+* confidence level is explicit
+* partial explanations are not presented as complete
+
+## Output format
+
+1. Problem statement
+2. Hypothesis tree
+3. Confirmed findings
+4. Rejected hypotheses
+5. Remaining uncertainties
+6. Root-cause conclusion
+7. Confidence level
+8. Recommended next steps
+
+## Gotcha
+
+* The model tends to lock onto the first plausible explanation too early.
+* Contradictory evidence usually means the current conclusion is wrong or incomplete.
+* Many production issues are caused by multiple interacting factors, not one neat bug.
+
+## Do NOT
+
+* Do NOT present guesses as facts
+* Do NOT skip rejected hypotheses
+* Do NOT stop after one plausible explanation
+* Do NOT ignore version-specific or package-specific behavior
+* Do NOT claim full root cause if meaningful uncertainty remains

package/.agent-src/skills/project-analysis-laravel/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: project-analysis-laravel
+description: "Use for deep Laravel project analysis: boot flow, request lifecycle, container usage, Eloquent/data flow, async systems, and Laravel-specific failure patterns."
+source: package
+---
+
+# project-analysis-laravel
+
+## When to use
+
+Use this skill when:
+
+* The project uses Laravel
+* A deep Laravel-specific architecture or runtime analysis is needed
+* `universal-project-analysis` routes here after framework detection
+* A broad issue spans routes, middleware, services, models, queues, config, or infrastructure
+
+Do NOT use when:
+
+* The task is a small isolated Laravel coding change
+* The issue is already narrowed to a specific specialist skill
+* The project is not actually Laravel
+
+## Core principles
+
+* Installed Laravel version controls behavior
+* Boot order matters
+* Middleware order matters
+* Container behavior must be traced, not assumed
+* Eloquent behavior often hides real execution cost
+* Async boundaries create hidden state problems
+
+## Procedure
+
+### 1. Confirm Laravel version and runtime
+
+Check: `composer.lock`, `composer.json`, `artisan --version`, PHP version and runtime environment.
+Validate: Laravel version is explicit, major supporting packages are identified, deployment/runtime shape is known.
+
+### 2. Analyze boot and configuration
+
+Inspect: service providers, provider registration order, config files, cached config/route state, middleware registration, route groups and prefixes, env/config interaction.
+
+Check:
+
+* config caching risks
+* `env()` usage outside config
+* provider misuse
+* route cache assumptions
+* driver choices for queue/cache/mail/session/filesystem
+
+### 3. Trace request-to-response flow
+
+Trace: route → middleware → FormRequest/validation → controller → service/action → model/repository/query → events/observers → response transformation.
+
+Validate: authorization path is visible, validation path is visible, transaction boundaries are visible, hidden side effects are identified.
+
+### 4. Analyze data and Eloquent flow
+
+Inspect: migrations, model relationships, casts/enums/json usage, soft deletes, nullable assumptions, eager/lazy loading, indexes and query shape.
+
+Check:
+
+* N+1 risks
+* mismatches between schema and model assumptions
+* unexpected model event behavior
+* wrong relationship direction or ownership
+
+### 5. Analyze async and infrastructure flow
+
+Inspect: queued jobs, event listeners, scheduled commands, broadcasting, cache invalidation, mail/notification side effects, external HTTP integrations.
+
+Check:
+
+* serialization risks
+* tenant/user context loss
+* idempotency
+* retry loops
+* stale cache / eventual consistency
+* side effects inside transactions
+
+### 6. Analyze test posture
+
+Check: feature tests, unit tests, integration coverage, factories/seeders/fakes, missing tests on critical paths.
+Validate: risky paths have test coverage, async behavior has meaningful tests, infrastructure assumptions are testable.
+
+### 7. Validate Laravel analysis quality
+
+Check:
+
+* boot flow is explicit
+* request/data/async boundaries are mapped
+* Laravel version-specific behavior was considered
+* hidden framework side effects are identified
+* next specialist skill is clear where needed
+
+## Output format
+
+1. Laravel version and runtime summary
+2. Boot/config findings
+3. Request-to-response flow
+4. Data/Eloquent findings
+5. Async/infrastructure findings
+6. Test posture
+7. Key risks and next steps
+
+## Gotcha
+
+* Laravel hides complexity behind convenient abstractions.
+* Middleware, observers, facades, and Eloquent can make execution flow look simpler than it is.
+* Cached config/routes can make the real runtime differ from the source code.
+
+## Do NOT
+
+* Do NOT assume Laravel behavior without version context
+* Do NOT stop at controller/service level if observers, jobs, or events are involved
+* Do NOT ignore middleware order
+* Do NOT ignore config/cache/runtime differences
+* Do NOT treat Eloquent convenience as proof of correctness or performance

package/.agent-src/skills/project-analysis-nextjs/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: project-analysis-nextjs
+description: "Use for deep Next.js analysis: server vs client boundaries, routing, data fetching, caching, rendering modes, and hydration/runtime issues."
+source: package
+---
+
+# project-analysis-nextjs
+
+## When to use
+
+Use this skill when:
+
+* The project uses Next.js
+* There are SSR, SSG, ISR, or hydration issues
+* Data fetching or caching behavior is unclear
+* Client vs server behavior is inconsistent
+* `universal-project-analysis` routes here after detecting Next.js
+
+Do NOT use when:
+
+* The task is a simple UI change
+* The issue is purely React-local and not Next-specific
+* The project is not Next.js
+
+## Core principles
+
+* Server and client are different execution environments
+* Rendering mode determines behavior
+* Data fetching defines lifecycle
+* Caching changes reality
+* Hydration must match server output
+* Edge and Node runtimes behave differently
+
+## Procedure
+
+### 1. Identify Next.js setup
+
+Check: Next.js version, App Router vs Pages Router, deployment target (Node vs Edge), TypeScript or JavaScript, config files.
+Validate: routing system is clear, runtime environment is known.
+
+### 2. Determine rendering model
+
+Identify: SSR, SSG, ISR, client-side rendering.
+Check: which pages/components use which mode, unexpected rendering mode switches, static vs dynamic boundaries.
+
+### 3. Analyze server vs client boundaries
+
+Inspect: server components, client components (`"use client"`), shared components.
+
+Check:
+
+* server-only code in client components
+* client-only logic in server components
+* unexpected serialization issues
+
+### 4. Trace data fetching
+
+Inspect: `fetch`, `getServerSideProps`/`getStaticProps` (Pages Router), server actions, API routes.
+
+Check:
+
+* where data is fetched
+* duplication of requests
+* incorrect caching
+* missing revalidation
+
+### 5. Analyze caching behavior
+
+Check: fetch caching options, revalidation settings, route segment config, browser vs server cache differences.
+Validate: stale data issues, unexpected cache hits, missing invalidation logic.
+
+### 6. Analyze routing and navigation
+
+Inspect: route structure, dynamic routes, layouts, navigation patterns.
+Check: incorrect routing assumptions, layout reuse issues, navigation inconsistencies.
+
+### 7. Detect hydration and runtime issues
+
+Check: server vs client output mismatch, conditional rendering differences, browser-only APIs used on server, timezone/randomness differences.
+Validate: hydration warnings, inconsistent UI between server and client.
+
+### 8. Detect common Next.js anti-patterns
+
+* mixing server and client concerns incorrectly
+* overusing client components
+* fetching data in the wrong layer
+* ignoring caching behavior
+* duplicating fetch logic across layers
+
+### 9. Validate Next.js analysis quality
+
+Check:
+
+* rendering mode is explicit
+* server/client boundary is clear
+* data fetching flow is mapped
+* caching behavior is understood
+* hydration issues are explained
+
+## Output format
+
+1. Next.js setup summary
+2. Rendering model overview
+3. Server vs client boundary analysis
+4. Data fetching findings
+5. Caching behavior findings
+6. Routing findings
+7. Hydration/runtime issues
+8. Key risks and fixes
+
+## Gotcha
+
+* Many bugs come from misunderstanding server vs client boundaries.
+* Caching can make correct code appear broken.
+* Hydration errors often indicate mismatched assumptions, not simple bugs.
+
+## Do NOT
+
+* Do NOT assume everything runs on the client
+* Do NOT ignore caching behavior
+* Do NOT mix server and client logic blindly
+* Do NOT debug hydration issues without checking rendering differences
+* Do NOT treat Next.js as "just React"

package/.agent-src/skills/project-analysis-node-express/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: project-analysis-node-express
+description: "Use for deep Node.js / Express project analysis: boot flow, middleware order, async behavior, data layer, auth/security, and Node-specific runtime failure patterns."
+source: package
+---
+
+# project-analysis-node-express
+
+## When to use
+
+Use this skill when:
+
+* The project uses Node.js with Express or a similar middleware-based HTTP stack
+* A deep framework/runtime analysis is needed
+* `universal-project-analysis` routes here after framework detection
+* The issue spans middleware, async behavior, data access, or runtime/process handling
+
+Do NOT use when:
+
+* The task is a small isolated change
+* The project is not Node/Express-like
+* The issue is already isolated to another specialist skill
+
+## Core principles
+
+* Middleware order changes behavior
+* Async mistakes often look like business logic bugs
+* Process/runtime state matters in Node
+* Package/version mismatches are common in JS ecosystems
+* Event loop and connection management must be treated as first-class concerns
+
+## Procedure
+
+### 1. Confirm runtime and framework shape
+
+Check: `package.json`, lock file, Node version requirements, entrypoint files, Express or similar framework usage, TS/JS setup, env/config loading.
+Validate: Node/runtime version is explicit, major packages are identified, app entrypoint and boot path are known.
+
+### 2. Analyze app boot and middleware registration
+
+Inspect: server bootstrap, env/config loading, `app.use()` order, route registration, error middleware, DB connection startup, graceful shutdown handling.
+
+Check:
+
+* middleware order correctness
+* error middleware shape (must have 4 params)
+* CORS/body parsing/auth order
+* startup/shutdown safety
+
+### 3. Trace request-to-response flow
+
+Trace: route → middleware chain → controller/handler → service layer → ORM/query layer → response handling.
+Validate: request lifecycle is explicit, input validation/auth/error handling are visible, "headers already sent" or double-response risks are identified.
+
+### 4. Analyze async/runtime behavior
+
+Inspect: async middleware, `await` usage, promise handling, background jobs/workers, stream usage, event listeners, shared module state.
+
+Check:
+
+* missing awaits
+* unhandled rejections
+* race conditions
+* event-loop blocking
+* memory leaks
+* circular dependency symptoms
+
+### 5. Analyze data and security flow
+
+Inspect: ORM/query layer, transactions, auth/token/session logic, rate limiting, input sanitization, raw SQL usage.
+
+Check:
+
+* pool exhaustion
+* migration/schema drift
+* JWT/session risks
+* string interpolation risks
+* trust boundary mistakes
+
+### 6. Validate Node/Express analysis quality
+
+Check:
+
+* runtime version and package versions are explicit
+* middleware order is mapped
+* async and process-level behavior are analyzed
+* auth/data/runtime risks are evidence-based
+* next specialist skill is clear if needed
+
+## Output format
+
+1. Runtime/framework summary
+2. Boot/middleware findings
+3. Request/async flow findings
+4. Data/security findings
+5. Runtime/process risks
+6. Key risks and next steps
+
+## Gotcha
+
+* In Node/Express systems, process/runtime behavior often explains bugs more than route code does.
+* Middleware order and async mistakes can silently corrupt behavior without obvious stack traces.
+* Shared module state and package hoisting/version mismatches create hidden cross-request problems.
+
+## Do NOT
+
+* Do NOT ignore middleware order
+* Do NOT assume async code is correct just because no exception is thrown
+* Do NOT ignore process-level behavior, shutdown, or shared module state
+* Do NOT treat package/tutorial examples as version-safe without checking installed versions
+* Do NOT stop at route handlers if the failure pattern points to runtime or middleware behavior