@event4u/agent-config 1.9.1

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

@@ -0,0 +1,143 @@
+---
+name: command-writing
+description: "Use when creating or editing a slash command in .agent-src.uncompressed/commands/ — frontmatter, numbered steps, safety gates — even when the user just says 'add a /command for X'."
+source: package
+---
+
+# command-writing
+
+## When to use
+
+* Creating a new slash command in `.agent-src.uncompressed/commands/{name}.md`
+* Rewriting an existing command (not a typo fix)
+* Deciding whether a request should be a command at all
+* Splitting an oversized command into smaller ones
+
+Do NOT use this skill when:
+
+* The content is a constraint the agent must always honor → use `rule-writing`
+* The content is reference knowledge agents cite → use `guideline-writing`
+* The content is a triggered workflow invoked by the model → use `skill-writing`
+
+## Command vs skill — critical test
+
+| Intent | Artifact |
+|---|---|
+| "User types `/foo` to explicitly run this" | **Command** |
+| "Agent picks this up from description match" | **Skill** |
+
+A command is **user-invoked** and carries `disable-model-invocation: true`.
+A skill is model-invoked via description routing. If both audiences apply,
+author as a skill and add a thin command that delegates to it.
+
+## Procedure
+
+### 0. Run the Drafting Protocol
+
+Creating or materially rewriting a command **must** go through Understand →
+Research → Draft from the
+[`artifact-drafting-protocol`](../../rules/artifact-drafting-protocol.md) rule.
+
+* **Understand** — what user-facing problem does `/{name}` solve in one
+  session? What are the inputs, outputs, side effects?
+* **Research** — **inspect** `.agent-src.uncompressed/templates/command.md`,
+  grep `commands/` for overlap, and **analyze** 1–2 peer commands
+  (e.g. `create-pr`, `commit`).
+* **Draft** — propose frontmatter (`name`, `description`) first, then the
+  step skeleton. Only fill bodies after both are confirmed.
+
+### 1. Use the template
+
+Canonical source: `.agent-src.uncompressed/templates/command.md`.
+
+Minimum frontmatter:
+
+```yaml
+---
+name: {command-name}          # must match filename without .md
+description: "Short human-readable summary of what /{name} does"
+disable-model-invocation: true
+skills: [optional-skill-1]    # optional — skills this command delegates to
+---
+```
+
+When iterating on the description, delegate to the
+[`description-assist`](../description-assist/SKILL.md) skill — approval-gated,
+no silent edits, max two rounds.
+
+### 2. Structure the body
+
+Required sections in this order:
+
+1. `# /{name}` heading + one-line summary
+2. **Source of truth note** — works on `.agent-src.uncompressed/`, never on
+   generated directories
+3. `## Steps` — numbered sub-headings `### 1.`, `### 2.`, ...
+4. Final step **presents findings** and asks the user before destructive
+   changes (numbered options per `user-interaction` rule)
+5. Optional `## Rules` — short, command-specific constraints
+
+### 3. Enforce safety gates
+
+* No auto-apply of destructive actions without user confirmation.
+* Every step with side effects (git push, file delete, PR merge) asks first.
+* If the command calls external APIs, list required keys / permissions.
+* If the command edits agent files, target `.agent-src.uncompressed/` only.
+
+### 4. Enforce the size budget
+
+Normative source: [`size-enforcement`](../../rules/size-enforcement.md) +
+`guidelines/agent-infra/size-and-scope.md`.
+
+| Category | Target |
+|---|---|
+| Ideal | ≤ 120 lines |
+| Acceptable | ≤ 200 lines |
+| Split signal | > 250 lines |
+
+Commands orchestrate, they do not implement detail. If a step needs a
+multi-paragraph explanation, extract it into a skill and call it.
+
+### 5. Validate
+
+* Run `python3 scripts/skill_linter.py .agent-src.uncompressed/commands/{name}.md`
+  → 0 FAIL.
+* Run `task sync` → regenerates `.agent-src/commands/{name}.md`.
+* Run `task generate-tools` → creates the Claude symlink at
+  `.claude/skills/{name}/SKILL.md`.
+* Run `task ci` → exits 0 except for tolerated warnings.
+
+## Output format
+
+1. Complete command file at `.agent-src.uncompressed/commands/{name}.md`
+2. Frontmatter populated, `disable-model-invocation: true` present
+3. Linter output showing 0 FAIL
+4. Generated Claude symlink verified
+
+## Gotchas
+
+* Forgetting `disable-model-invocation: true` — the model will auto-invoke
+  the command as if it were a skill.
+* Numbered options without a "skip" / "no change" path.
+* Steps that silently apply destructive changes — always show summary + ask.
+* Referring to `.augment/` paths for editing — source of truth is
+  `.agent-src.uncompressed/`.
+* Duplicating another command's workflow instead of delegating via `skills:`.
+
+## Do NOT
+
+* Do NOT set `disable-model-invocation: false`
+* Do NOT auto-apply destructive actions
+* Do NOT inline skill-level detail — delegate
+* Do NOT edit `.agent-src/`, `.augment/`, or `.claude/` projections
+* Do NOT exceed the hard size limit without a waiver
+
+## Examples
+
+Good description (trigger-shaped, outcome-focused):
+
+> "Create a GitHub PR with structured description from Jira ticket and code changes"
+
+Bad description (vague, no outcome):
+
+> "PR command"

package/.agent-src/skills/composer-packages/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: composer-packages
+description: "Use when building or maintaining a Composer library — versioning, Laravel integration, autoloading, publishing to private registries — even when the user says 'release a new version'."
+source: package
+---
+
+# composer-packages
+
+## When to use
+
+Use this skill when creating, maintaining, or publishing Composer library packages — including Laravel packages with service providers, Artisan commands, and config publishing.
+
+## Procedure: Work with Composer packages
+
+1. Read the package's `composer.json` for structure and dependencies.
+2. Check if it's a Laravel package (look for `extra.laravel.providers`).
+3. Read the package's `README.md` and `CHANGELOG.md`.
+4. Check the `agents/` directory in the package for package-specific docs.
+
+## Known packages
+
+Check the project's `composer.json` for organization-specific packages.
+Check `agents/overrides/skills/composer-packages.md` for the package registry and known packages list.
+
+## Package structure
+
+```
+my-package/
+├── src/                    # Source code
+│   ├── App/
+│   │   └── Providers/      # Laravel service providers
+│   └── ...
+├── config/                 # Publishable config files
+├── tests/                  # Package tests
+├── composer.json           # Package manifest
+├── README.md               # Documentation
+├── CHANGELOG.md            # Version history
+└── agents/                 # Package-specific agent docs
+```
+
+## composer.json essentials
+
+### Required fields
+
+```json
+{
+    "name": "vendor/my-package",
+    "type": "library",
+    "description": "Clear, concise description",
+    "require": {
+        "php": "^8.2"
+    },
+    "autoload": {
+        "psr-4": {
+            "Vendor\\MyPackage\\": "src/"
+        }
+    }
+}
+```
+
+### Laravel package auto-discovery
+
+```json
+{
+    "extra": {
+        "laravel": {
+            "providers": [
+                "Vendor\\MyPackage\\App\\Providers\\PackageServiceProvider"
+            ]
+        }
+    }
+}
+```
+
+### Composer scripts / plugins
+
+Packages can hook into Composer lifecycle events:
+
+```json
+{
+    "scripts": {
+        "post-install-cmd": [
+            "MyNamespace\\ComposerScripts::onInstall"
+        ]
+    }
+}
+```
+
+## Version constraints
+
+Use **wide version ranges** for library packages to maximize compatibility:
+
+```json
+{
+    "require": {
+        "php": "^8.1 || ^8.2 || ^8.3 || ^8.4",
+        "illuminate/support": "^10.0 || ^11.0 || ^12.0"
+    }
+}
+```
+
+**Libraries** should use `||` ranges. **Applications** should use `^` (caret).
+
+## Local development
+
+### Path repositories
+
+In the consuming project's `composer.json`:
+
+```json
+{
+    "repositories": [
+        { "type": "path", "url": "../packages/my-package" }
+    ]
+}
+```
+
+Then: `composer require vendor/my-package:@dev`
+
+### Development project
+
+If the organization has a dedicated development sandbox for testing packages, use it for local testing.
+
+## Publishing
+
+### Private registry (GitHub Packages / Satis)
+
+Packages are published to a private Composer registry. Check the organization's Satis or GitHub Packages setup.
+
+### Pre-publish checklist
+
+1. `composer validate` — verify `composer.json` is valid.
+2. `composer dump-autoload` — verify autoloading works.
+3. Run tests: `vendor/bin/phpunit` or `vendor/bin/pest`.
+4. Run quality tools: PHPStan, ECS, Rector.
+5. Update `CHANGELOG.md` with the new version.
+6. Tag the release: `git tag v1.2.3`.
+
+## Conventions
+
+- Follow the organization's namespace convention (check existing packages).
+- Use `declare(strict_types=1)` in all PHP files.
+- Use typed properties, parameters, and return types.
+- Follow the same coding standards as the main projects (see `php-coder` skill).
+- Include `agents/` directory for package-specific documentation.
+
+
+## Output format
+
+1. Package files following standard Composer structure
+2. Updated composer.json with correct autoloading and dependencies
+3. Service provider and config publishing (if Laravel package)
+
+## Auto-trigger keywords
+
+- Composer package
+- library development
+- package versioning
+
+## Gotcha
+
+- Don't add `composer.lock` to library packages — it should be in `.gitignore` for libraries (not apps).
+- Minimum stability must be explicit — don't assume `stable`.
+- The model tends to set overly restrictive version constraints — use `^` (caret) not `=` (exact).
+
+## Do NOT
+
+- Do NOT use `*` version constraints in library packages.
+- Do NOT require specific patch versions — use `^` or `||` ranges.
+- Do NOT include dev dependencies in `require` — use `require-dev`.
+- Do NOT forget to run `composer validate` before publishing.
+- Do NOT publish without updating the changelog and tagging.

package/.agent-src/skills/context-authoring/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: context-authoring
+description: "Use when filling in knowledge-layer context files — auth-model, tenant-boundaries, data-sensitivity, deployment-order, observability — interactive walkthrough that turns templates into reviewer fuel."
+source: package
+---
+
+# context-authoring
+
+## When to use
+
+Use this skill when:
+
+- A new project has been scaffolded and the `agents/contexts/` files are still
+  template stubs from `event4u/agent-config`.
+- The user asks "help me fill in the auth model context", "set up tenant
+  boundaries", or similar knowledge-layer work.
+- A reviewer skill (`authz-review`, `data-flow-mapper`, `migration-safety`,
+  `multi-tenant-boundary-review`, `secrets-and-config-review`) reports *"I
+  cannot proceed — `agents/contexts/<file>.md` is still a template"*.
+- After a significant architecture change that invalidates one of the five
+  context files.
+
+Do NOT use when:
+
+- Writing a regular roadmap or feature doc — use `agent-docs-writing`.
+- Creating a generic context document that does not map to one of the five
+  knowledge-layer templates — use `context-create`.
+- Filling in the engineering-memory YAML files (`domain-invariants.yml`, etc.)
+  — use `/memory-add`.
+
+## The five files
+
+| File | What it answers | Who reads it |
+|---|---|---|
+| `auth-model.md` | Roles, permission model, impersonation, known exceptions | `authz-review`, `judge-security-auditor`, `threat-modeling` |
+| `tenant-boundaries.md` | Tenancy type, scope propagation, known cross-tenant paths | `multi-tenant-boundary-review`, `blast-radius-analyzer`, `judge-security-auditor` |
+| `data-sensitivity.md` | Field classification, masking rules, log-safe types | `data-exposure-review`, `data-flow-mapper`, logging reviewers |
+| `deployment-order.md` | Migration strategy, feature flags, rollback plan | `migration-safety`, `judge-bug-hunter`, release reviewers |
+| `observability.md` | Error tracking, log channels, metrics, known alerts | deploy reviewers, `bug-analyzer`, incident mode |
+
+The templates ship in `.agent-src.uncompressed/templates/contexts/` and are
+copied into `agents/contexts/` by the installer.
+
+## Procedure: context-authoring
+
+### Step 0: Inspect
+
+1. List `agents/contexts/` — which of the five files exist? Which still contain
+   the `<!-- Template shipped by event4u/agent-config. -->` HTML comment?
+2. Ask the user which file to work on. Use numbered options:
+
+   ```
+   > 1. auth-model.md — roles, permissions, impersonation
+   > 2. tenant-boundaries.md — tenancy type and scope propagation
+   > 3. data-sensitivity.md — field classification and masking
+   > 4. deployment-order.md — migrations, flags, rollback
+   > 5. observability.md — errors, logs, metrics, alerts
+   ```
+
+3. If multiple files are stubs, default to the order above — `auth-model` is
+   the prerequisite for `tenant-boundaries`; both feed `data-sensitivity`.
+
+### Step 1: Harvest evidence before asking
+
+For the chosen file, pull what the codebase already reveals before asking
+the user. Record the file:line citations — they become the authoritative
+source when the user is unsure.
+
+| File | Harvest from |
+|---|---|
+| `auth-model.md` | Policy classes, Gate definitions, permission seeders, role enums, `@can` directives, middleware |
+| `tenant-boundaries.md` | Base query scopes, connection-switching middleware, tenant-resolution service, global scopes, `.env` vars like `TENANT_*` |
+| `data-sensitivity.md` | Eloquent `$hidden` / `$casts`, Sentry `beforeSend`, logging helpers, API resources, export commands |
+| `deployment-order.md` | `database/migrations/`, feature-flag config (Pennant / LaunchDarkly), deploy scripts, CI workflow, rollback runbooks in `docs/` |
+| `observability.md` | `config/logging.php`, Sentry init, dashboard links in READMEs, alert rules in Terraform/Grafana dashboards |
+
+Start the walkthrough by showing the harvested evidence — the user only
+has to confirm or correct, not invent from scratch.
+
+### Step 2: Walk the template section by section
+
+1. Open the template and treat **every HTML comment** as a question for the
+   user. Do NOT fabricate answers to skip a section.
+2. Present each section as:
+
+   ```
+   **Section:** <heading>
+   **Template asks:** <what the comment says>
+   **Evidence I found:** <file:line references or "none">
+   **Proposed content:** <draft or "I need your input">
+
+   > 1. Accept the draft
+   > 2. Edit — tell me what's wrong
+   > 3. I don't know — mark as "TBD" with a follow-up task
+   ```
+
+3. If the user picks "TBD", insert an HTML comment `<!-- TBD: <question> -->`
+   at that spot — never a fabricated value. Reviewer skills key on the
+   comment to warn about incomplete sections.
+
+### Step 3: Preserve the file contract
+
+1. Remove the top-of-file `<!-- Template shipped by ... -->` comment only
+   after at least one section has been authored — an untouched file must
+   stay recognisable as a stub.
+2. Keep every heading the template ships with. Reviewer skills grep for
+   exact section names (`## Known exceptions`, `## Known alerts`, etc.).
+3. Do NOT add new top-level sections. The template surface is the
+   contract — extend existing sections, file a proposal via
+   `learning-to-rule-or-skill` to expand the template upstream.
+
+### Step 4: Validate
+
+1. Run `python3 scripts/check_portability.py` — project-specific content is
+   expected here, but the check catches accidental copy of other projects'
+   identifiers.
+2. Run `python3 scripts/check_references.py` — cross-file links between the
+   five contexts must resolve.
+3. Confirm with the user: "is this accurate enough that a reviewer should
+   treat it as the source of truth?" — anything less and a `<!-- TBD -->`
+   marker stays.
+
+## Output format
+
+1. `agents/contexts/<file>.md` updated with project-specific content; every
+   section either authored or explicitly marked `<!-- TBD: ... -->`.
+2. A short summary comment back to the user: which sections are complete,
+   which are `TBD`, and which downstream reviewer skills are now unblocked.
+3. Optional: a proposal stub in `agents/learnings/` for any template gap
+   the user hit (missing section, ambiguous field) — feeds the curated
+   self-improvement pipeline via `learning-to-rule-or-skill`.
+
+## Gotcha
+
+- The model tends to fabricate plausible roles, fields, or alerts when
+  harvesting comes up empty. Do NOT. An `<!-- TBD: ... -->` marker is
+  always better than a made-up entry — reviewer skills trust this file.
+- The model tends to collapse the template once it starts editing, losing
+  the HTML comments that explain *why* a section exists. Preserve them
+  until the section is authored — they are the authoring prompt.
+- `data-sensitivity.md` is the highest-leverage file and also the one most
+  likely to be skipped as "boring". Prioritise it after `auth-model` —
+  missing entries here become production leaks, not review nits.
+- Do not treat this skill as a form-filler. If a project is single-tenant,
+  `tenant-boundaries.md` SHOULD be deleted, not stubbed — the checklist
+  explicitly says so at the top of the file.
+
+## Do NOT
+
+- Do NOT copy content between projects. Every context file is local to its
+  repo. Reuse of another project's roles, tenants, or alerts is a
+  portability violation and a security risk.
+- Do NOT commit TBD-heavy files without flagging them in the PR
+  description. Reviewer skills will downgrade confidence, but a human
+  reviewer should know the contexts are partial.
+- Do NOT rename or restructure the template sections. Reviewer skills
+  grep for exact headings.

package/.agent-src/skills/context-document/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: context-document
+description: "Use when the user says "create context", "document this area", or wants a structured snapshot of a codebase area for agent orientation."
+source: package
+---
+
+# context
+
+## When to use
+
+Use this skill when:
+- Documenting a module, service, or integration for future reference
+- Exploring an unfamiliar area of the codebase
+- Preparing for a feature that touches multiple areas
+- Onboarding to a new part of the codebase
+
+
+Do NOT use when:
+- Writing code or features
+- Creating roadmaps (use `roadmap-management` skill)
+
+## Procedure: Manage contexts
+
+1. **Identify scope** — Which area of the codebase needs a context document?
+2. **Research** — Use codebase-retrieval to understand the area (files, patterns, dependencies).
+3. **Write or update** — Create/update the context doc following the template below.
+4. **Verify** — Confirm all referenced files exist and descriptions match current code.
+
+A **context document** is a structured snapshot of a codebase area:
+- What it does, why it exists
+- Key files, classes, and patterns
+- Database tables and API endpoints
+- Dependencies and known issues
+
+Unlike feature plans (future-focused) or roadmaps (task-focused), contexts are
+**present-focused** — they describe the current state of the code.
+
+## File structure
+
+```
+.augment/contexts/                       # Shared contexts (about the agent system itself)
+├── augment-infrastructure.md
+├── skills-and-commands.md
+└── documentation-hierarchy.md
+
+agents/contexts/                         # Project-wide contexts
+├── {context-name}.md
+
+app/Modules/{Module}/agents/contexts/    # Module-scoped contexts
+├── {context-name}.md
+
+.augment/templates/
+└── contexts.md                          # Context template
+```
+
+## Context types
+
+| Type | Scope | Example |
+|---|---|---|
+| **Module** | Single module's structure and purpose | `client-software.md` |
+| **Domain** | Business domain across modules | `import-pipeline.md` |
+| **Service** | Complex service with its dependencies | `customer-service.md` |
+| **Integration** | External API/system integration | `probaus-api.md` |
+| **Infrastructure** | DevOps or infrastructure concern | `queue-system.md` |
+
+## Where to store contexts
+
+| Content | Location |
+|---|---|
+| About the `.augment/` system itself | `.augment/contexts/` (shared package) |
+| Project-wide or cross-module | `agents/contexts/` |
+| Module-specific | `app/Modules/{Module}/agents/contexts/` |
+| If unsure | Ask the user |
+
+### Shared vs. project-specific contexts
+
+**`.augment/contexts/`** — Part of the shared package. Describes the agent infrastructure:
+how overrides work, what skills/commands exist, the documentation hierarchy.
+These are read-only at project level (like all `.augment/` content).
+
+**`agents/contexts/`** — Project-specific. Describes the project's business domain:
+modules, services, integrations, database architecture.
+These are created and maintained per project.
+
+## Integration with other systems
+
+### Sessions
+When working in an area that has a context document, load it at session start.
+The session's Context section can reference it.
+
+### Features
+Before planning a feature, check if a context document exists for the affected area.
+It provides the baseline understanding needed for planning.
+
+### Module exploration
+`/module-explore` gathers the data needed to create a module context.
+`/context-create` turns that exploration into a persistent document.
+
+### Overrides
+When customizing a shared skill or command, read `.augment/contexts/override-system.md` for the naming conventions and format.
+
+### Shared contexts
+When working on the agent infrastructure itself (skills, commands, rules), check
+`.augment/contexts/` for existing documentation about the system.
+
+## Behavior rules
+
+### Creating contexts
+
+1. **Always analyze the code first** — use `codebase-retrieval`, `view`, and file listing.
+2. **Be factual** — describe what IS, not what SHOULD be.
+3. **Be specific** — link to files, name classes, reference tables.
+4. **Ask the user** about anything unclear.
+
+### Maintaining contexts
+
+- Update `Last Updated` when modifying.
+- When code changes affect a context, update it.
+- `/context-refactor` is the dedicated command for this.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `context-create` | Analyze an area and create a new context document |
+| `context-refactor` | Revisit, update, and extend an existing context |
+
+
+## Output format
+
+1. Context document in the correct location with structured sections
+2. Cross-references to related contexts updated
+
+## Auto-trigger keywords
+
+- context document
+- codebase context
+- orientation doc
+- context creation
+
+## Gotcha
+
+- Context docs become stale — always check the actual code before trusting a context document.
+- Don't create context docs for areas that change weekly — they'll be outdated immediately.
+- Keep context docs factual, not aspirational — document what IS, not what should be.
+
+## Do NOT
+
+- Do NOT create contexts without analyzing the code first.
+- Do NOT guess about architecture — verify by reading the code.
+- Do NOT duplicate information from `AGENTS.md` — reference it instead.
+- Do NOT commit or push without permission.
+- Do NOT create contexts for trivial areas — only when the knowledge is worth persisting.

package/.agent-src/skills/conventional-commits-writing/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: conventional-commits-writing
+description: "Use when writing commit messages or squash-merge titles — `feat:`, `fix:`, `chore:`, scopes, breaking changes — even when the user just says 'commit this' without naming Conventional Commits."
+source: package
+execution:
+  type: assisted
+  handler: internal
+  allowed_tools: []
+---
+
+# conventional-commits-writing
+
+## When to use
+
+- Generating commit message from staged changes
+- Generating squash merge title from PR
+- Deciding correct type for a change
+- Reviewing/correcting commit messages
+- Splitting vague changes into multiple commits
+
+NOT: explaining standard (reference rule), git workflow (use `git-workflow`)
+
+## Procedure: Generate
+
+1. **Intent** — feat/fix/refactor/docs/test/ci/chore/perf/build/style. Classify by intent, not file type.
+2. **Mixed concerns?** — split into multiple commits or choose dominant net effect for squash title.
+3. **Scope** — Jira ID or area name. Only if it adds clarity.
+4. **Description** — intent, not implementation. Imperative. Max 72 chars. No generic filler.
+5. **Breaking?** — add `!` or `BREAKING CHANGE:` footer:
+
+```
+feat(api)!: rename invoice status values
+```
+
+6. **Validate** — type matches intent? scope useful? not hiding multiple concerns?
+
+## Procedure: Review
+
+Parse → check type vs diff → check scope → check description clarity → suggest corrections.
+
+## Procedure: Squash merge title
+
+Read all PR commits → identify net effect → write single Conventional Commit summarizing it.
+
+## Output
+
+1. Recommended message(s)
+2. Brief type rationale
+3. Split suggestion if needed
+
+## Gotcha
+
+- Model overuses `chore`/`refactor` — classify by intent, not effort
+- File type ≠ commit type (`.md` change can be `feat`)
+- `refactor` = NO behavior change — if behavior changes, use `feat`/`fix`
+- Squash title = net effect, not internal details
+
+## Do NOT
+
+- Do NOT use vague messages: `update stuff`, `fix bug`, `changes`
+- Do NOT use `refactor` for bug fixes
+- Do NOT use `chore` for meaningful behavior changes
+- Do NOT hide multiple unrelated concerns in one message
+- Do NOT omit breaking-change markers when compatibility changes
+
+## References
+
+- Rule: `commit-conventions` — format, types, scope
+- Guideline: `guidelines/php/git.md` — selection rules, anti-patterns, checklist
+- Command: `/commit` — uses this skill