@event4u/agent-config 1.9.1

package/.agent-src/skills/upstream-contribute/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: upstream-contribute
+description: "Use when a learning, new skill, rule improvement, or bug fix from a consumer project should be contributed back to the shared agent-config package."
+source: package
+execution:
+  type: assisted
+  handler: internal
+  allowed_tools: ["github"]
+---
+
+# upstream-contribute
+
+## When to use
+
+- A new skill was created in a project that should be shared across all projects
+- A rule or skill improvement was discovered that benefits all consumers
+- A bug was found in a shared skill, rule, or command
+- The `learning-to-rule-or-skill` skill identified something worth upstreaming
+- An override was created locally and should become the new default
+- A project-specific skill/rule could be **generalized** to benefit all consumers
+- The `upstream-proposal` rule suggested a contribution and user agreed
+
+Do NOT use when:
+
+- **The user has NOT given explicit consent** — this is the #1 rule
+- The content already exists in the shared package
+- The learning is truly one-off and cannot be generalized
+
+## Goal
+
+Contribute a learning, skill, rule, or fix from a consumer project back to the
+shared `agent-config` package — with correct file placement, quality gates, and PR structure.
+
+## Core principles
+
+- **⛔ Consent first** — NEVER create a PR, branch, or any upstream action without explicit user approval
+- **Universality first** — the contribution must work for ALL consumers, not just one project
+- **Generalize when possible** — project-specific content CAN become universal with adaptation
+- **Evidence-based** — learnings must have occurred 2+ times or be clearly generalizable
+- **Complete pairs** — both uncompressed and compressed versions required
+- **Quality verified** — must pass linter before PR creation
+- **Local benefit immediately** — use override for instant project benefit while PR is pending
+
+## Package repository
+
+The shared agent-config package lives at:
+
+```
+git@github.com:event4u-app/agent-config.git
+```
+
+GitHub: `https://github.com/event4u-app/agent-config`
+
+## Procedure
+
+### 0. Mandatory consent gate
+
+**This step is NON-NEGOTIABLE. No exceptions.**
+
+Before ANY upstream work (branch, files, PR), ask the user:
+
+```
+> 🔄 This [skill/rule/guideline] could improve the shared agent-config package.
+> [Brief explanation of what would be contributed and why it's valuable]
+>
+> 1. Yes — create an upstream PR
+> 2. No — keep it project-local only
+```
+
+- **If user picks 2** → STOP. Do not mention upstream again for this item.
+- **If user picks 1** → continue with the procedure below.
+- **If `project.upstream_repo` is empty in `.agent-settings.yml`** → ask the user to configure it first.
+- **NEVER skip this step**, even if the user previously agreed to other contributions.
+
+### 1. Determine contribution type
+
+| Type | Uncompressed path | Compressed path |
+|---|---|---|
+| **New skill** | `.agent-src.uncompressed/skills/{name}/SKILL.md` | `.augment/skills/{name}/SKILL.md` |
+| **New rule** | `.agent-src.uncompressed/rules/{name}.md` | `.augment/rules/{name}.md` |
+| **New command** | `.agent-src.uncompressed/commands/{name}.md` | `.augment/commands/{name}.md` |
+| **New guideline** | `.agent-src.uncompressed/guidelines/{category}/{name}.md` | `.augment/guidelines/{category}/{name}.md` |
+| **Update to existing** | Same path as original | Same path as original |
+
+### 2. Apply locally as override (immediate benefit)
+
+Create an override so the project benefits immediately:
+
+```
+agents/overrides/{type}/{name}.md
+```
+
+With frontmatter:
+
+```yaml
+---
+overrides: {type}/{name}
+mode: replace  # or extend
+---
+```
+
+This step is optional if the change is low-urgency.
+
+### 2b. Generalize project-specific content (if needed)
+
+If the content is project-specific but could be made universal:
+
+1. **Identify project-specific parts** — domain names, local paths, project conventions
+2. **Abstract them** — replace with generic patterns, configurable values, or examples
+3. **Show the user the diff** — original vs. generalized version
+4. **Get approval** — user must confirm the generalized version is correct
+
+Example: A project-specific "import-csv" skill → generic "file-import" skill with configurable format.
+
+### 3. Prepare the upstream contribution
+
+The agent needs access to the package repository. Ask the user:
+
+```
+> The improvement should go to the shared agent-config package.
+> I need to create a PR in `event4u-app/agent-config`.
+>
+> 1. I have the package repo cloned locally — tell me the path
+> 2. Clone it for me into a temp directory
+> 3. I'll handle the PR manually — just give me the files
+```
+
+**Option 1:** User provides path → work directly in that repo.
+
+**Option 2:** Clone into temp directory:
+
+```bash
+git clone git@github.com:event4u-app/agent-config.git /tmp/agent-config-upstream
+cd /tmp/agent-config-upstream
+```
+
+**Option 3:** Output the file contents as copyable blocks for the user.
+
+### 4. Create branch and files
+
+```bash
+cd {package-repo-path}
+git checkout main && git pull
+git checkout -b feat/skills/{name}  # or fix/rules/{name}, etc.
+```
+
+Create both files:
+
+- **Uncompressed version** → `.agent-src.uncompressed/{type}/{name}` (full, verbose, human-readable)
+- **Compressed version** → `.augment/{type}/{name}` (token-efficient, preserving all code blocks,
+  headings, frontmatter, validation, gotchas)
+
+For skills, the compressed version should be 40-60% shorter than uncompressed.
+For rules and commands, they are usually copied 1:1 (no compression).
+
+### 5. Ensure file quality
+
+The files must:
+
+- Have correct YAML frontmatter (`name`, `description`, `source: package`)
+- NOT contain project-specific references (no domain names, local paths, FQDNs)
+- Follow the skill/rule/command template structure
+- Have exactly one trailing newline
+
+### 6. Run quality gates (if working in the package repo)
+
+```bash
+task lint-skills                    # 0 FAIL required
+task check-compression              # No errors for this file
+task generate-tools                 # Regenerate symlinks
+task consistency                    # Everything in sync
+```
+
+If not in the package repo, note that these checks will run in CI after the PR is created.
+
+### 6b. Proposal gate — MANDATORY when a proposal doc exists
+
+If the contribution originates from a proposal under `agents/proposals/`
+(produced by `learning-to-rule-or-skill` via the pipeline in
+[`self-improvement-pipeline`](../../guidelines/agent-infra/self-improvement-pipeline.md)),
+run the Stage-4 gate before opening the PR:
+
+```bash
+python3 scripts/check_proposal.py agents/proposals/{slug}.md
+```
+
+**Hard refusal rule:** if `check_proposal.py` exits non-zero, STOP —
+do not create the branch, do not push, do not open the PR. Surface the
+findings to the user, ask them to fix the proposal (add evidence,
+remove TODO markers, complete required sections), then rerun.
+
+When no proposal doc exists (small fix, typo, pure bug-fix), skip this
+step and document the rationale in the PR body under the Promotion
+Gate.
+
+### 7. Commit and create PR
+
+Branch naming: `feat/skills/{name}`, `fix/rules/{name}`, `feat/commands/{name}`
+
+Commit message format:
+
+```
+feat(skills): add {name} skill
+fix(rules): improve {name} rule — {what changed}
+feat(commands): add {name} command
+```
+
+PR title: Same as commit message.
+
+PR body must use the package's PR template with these gates:
+
+- **Promotion Gate** — learning occurred 2+ times, improves correctness, prevents real failure
+- **Quality Gate** — linter passes, tests pass
+- **Universality Gate** — no project-specific assumptions, benefits all consumers
+- **Completeness Gate** — both versions present, symlinks regenerated
+
+### 8. After merge — clean up override
+
+Once the PR is merged and the package is updated in the project:
+
+```bash
+# In the consumer project
+rm agents/overrides/{type}/{name}.md
+composer update event4u/agent-config  # or npm update
+```
+
+The shared version now replaces the local override.
+
+## Output format
+
+1. Summary of what is being contributed (type, name, why)
+2. File contents for both uncompressed and compressed versions
+3. If working in the package repo: branch name, commit message, PR title
+4. If Option 3: copyable file blocks for the user to paste
+5. Reminder to clean up local override after upstream merge
+
+## Gotcha
+
+- Agent in consumer project doesn't know the package repo URL — this skill provides it
+- Agent may try to edit `.augment/` in the consumer project — that's read-only (symlinked)
+- Agent may forget the compressed version — both are mandatory
+- Agent may include project-specific references in the skill — must be universal
+- The `source` field in frontmatter must be `package`, not `project`
+- Agent may not have git access to the package repo — Option 3 handles this gracefully
+
+## Do NOT
+
+- **Do NOT create any upstream artifact without explicit user consent** — this is the #1 rule
+- **Do NOT open a PR if `check_proposal.py` blocks** — fix the proposal first (step 6b)
+- Do NOT edit `.augment/` in the consumer project — it's managed by the package
+- Do NOT submit project-specific content without generalizing it first
+- Do NOT skip the compressed version — both files are mandatory
+- Do NOT forget to clean up the local override after upstream merge
+- Do NOT bypass quality gates — they exist for a reason
+- Do NOT assume consent from a previous contribution — ask every time

package/.agent-src/skills/using-git-worktrees/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: using-git-worktrees
+description: "Use when starting parallel work in isolation from the current branch — spawn a git worktree with ignore-safety checks and a clean test baseline — even when the user says 'try this on the side'."
+source: package
+---
+
+# using-git-worktrees
+
+## When to use
+
+* Starting new work while the current branch is mid-work and you don't
+  want to stash or switch
+* Running two agents (Augment Code, Claude Code, Cursor) on the same
+  repo in parallel — each needs its own working directory
+* Experimenting with a refactor that may be thrown away — a throwaway
+  worktree is cheaper than a throwaway commit
+* A long-running build or test suite is busy in the current worktree
+
+Do NOT use when:
+
+* A small fix fits in one commit on the current branch — worktree
+  overhead is not worth it
+* The task is linear ("just finish this PR") — a single branch is simpler
+* The repo is tiny and branch-switching is instant — setup cost outweighs
+  isolation benefit
+* You are unsure which branch you want — pick the branch first
+
+## Goal
+
+Land in an **isolated, ignored, test-clean** worktree ready for
+implementation, without polluting the parent repo's working tree.
+
+## The Iron Law
+
+```
+NO WORKTREE WITHOUT VERIFIED IGNORE + CLEAN BASELINE.
+```
+
+An un-ignored worktree directory will get committed accidentally. A
+worktree with a failing baseline mixes pre-existing failures into new
+work and makes it impossible to tell what you broke.
+
+## Procedure
+
+### 1. Inspect current state
+
+Before creating anything, check existing conventions — do not assume:
+
+```bash
+git worktree list                              # already-active worktrees
+ls -d .worktrees worktrees 2>/dev/null         # project-local convention
+grep -i "worktree.*director" AGENTS.md CLAUDE.md 2>/dev/null
+```
+
+If a worktree on the target branch already exists, **reuse it**. Git
+refuses to check out a branch that is already live elsewhere.
+
+### 2. Pick directory convention
+
+Stop at the first match — do not ask if discovered:
+
+| Found                    | Use                                        |
+|--------------------------|--------------------------------------------|
+| `.worktrees/` exists     | `.worktrees/<branch-name>`                 |
+| `worktrees/` exists      | `worktrees/<branch-name>`                  |
+| `AGENTS.md` preference   | follow it                                  |
+| nothing found            | ask user (numbered options)                |
+
+Ask format:
+
+> 1. `.worktrees/` — project-local, hidden (recommended)
+> 2. `worktrees/` — project-local, visible
+> 3. `~/.config/agent-config/worktrees/<project>/` — global
+
+### 3. Verify ignore-safety (project-local only)
+
+```bash
+git check-ignore -q .worktrees || git check-ignore -q worktrees
+```
+
+**If exit ≠ 0:** add the path to `.gitignore`, commit that change
+**before** creating the worktree. Do not proceed until the check
+passes. For the global location, skip — path is outside the repo.
+
+### 4. Create the worktree
+
+```bash
+git worktree add .worktrees/<branch-name> -b <branch-name>
+cd .worktrees/<branch-name>
+```
+
+Branch names must match the project convention — see
+`commit-conventions` rule.
+
+### 5. Install dependencies + verify baseline
+
+Auto-detect from manifest files:
+
+| File              | Command                                 |
+|-------------------|-----------------------------------------|
+| `composer.json`   | `composer install`                      |
+| `package.json`    | `npm ci` / `pnpm install` / `yarn`      |
+| `pyproject.toml`  | `poetry install` or `pip install -e .`  |
+| `Cargo.toml`      | `cargo build`                           |
+| `go.mod`          | `go mod download`                       |
+
+Run the project's fastest test target. If the baseline **fails**, stop
+and report — ask whether to fix main first or proceed. Never silently
+continue with a red baseline.
+
+## Multi-tool parallel work
+
+Agents share the same `.git/` but get their own working directory. One
+worktree per agent session; branch name encodes agent/task
+(`feat/augment-auth`, `feat/claude-refactor`). Merge or discard before
+starting a new worktree on the same branch.
+
+## Gotcha
+
+* **Un-ignored directory** — contents end up tracked; `git status`
+  noise across the whole repo. Verify first.
+* **Two worktrees on same branch** — git refuses; pick a new branch.
+* **Hardcoded `npm install`** on a PHP project fails silently. Detect
+  from manifest files.
+* **Skipping baseline** — failing tests pre-existed; later blamed on
+  your own changes.
+
+## Output format
+
+1. **Location** — full path to the worktree
+2. **Branch** — created branch name
+3. **Baseline** — `<N> tests passing` or explicit failure report
+4. **Next step** — suggested skill or command for the actual work
+
+## Do NOT
+
+* NEVER create a worktree before the ignore check passes
+* NEVER skip the baseline test run
+* NEVER reuse a directory name that already holds a worktree
+* NEVER `rm -rf` a worktree — use `git worktree remove`
+
+## Handover
+
+| Task                       | Skill / command                   |
+|----------------------------|-----------------------------------|
+| Finishing the branch       | `finishing-a-development-branch`  |
+| Opening the PR             | `/create-pr`                      |
+| Verifying completeness     | `verify-before-complete`          |

package/.agent-src/skills/validate-feature-fit/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: "validate-feature-fit"
+description: "Validate whether a feature request fits the existing codebase — check for duplicates, contradictions, scope creep, and architectural misfit"
+source: package
+execution:
+  type: assisted
+  handler: internal
+  allowed_tools: []
+---
+
+# Validate Feature Fit
+
+## When to use
+
+- The `improve-before-implement` rule detected a potential misfit
+- User explicitly asks to validate a feature idea before implementing
+- A feature request seems to overlap with existing functionality
+- A requested approach contradicts established patterns
+
+## Procedure
+
+### 1. Understand the request
+
+Read the feature description / user message. Extract:
+- **Goal**: What should be achieved?
+- **Scope**: What files/modules are affected?
+- **Approach**: How does the user want it done?
+
+### 2. Check for duplicates
+
+Search the codebase for existing functionality that covers (partially or fully) the same goal:
+- Services with similar names or methods
+- Controllers handling similar routes
+- Models with similar scopes or relations
+- Existing tests covering similar behavior
+
+**If duplicate found** → report with file references, suggest extending vs. duplicating.
+
+### 3. Check for contradictions
+
+Verify the request doesn't conflict with:
+- Existing module boundaries (does it cross module lines?)
+- Established patterns (does it introduce a new pattern where one exists?)
+- Naming conventions (does it use different naming than the codebase?)
+- Data flow (does it bypass existing services or repositories?)
+- **Product rules and domain invariants** — pull active rules via the
+  shared abstraction (see
+  [`memory-access`](../../guidelines/agent-infra/memory-access.md)):
+
+  ```python
+  from scripts.memory_lookup import retrieve
+  matches = retrieve(
+      types=["product-rules", "domain-invariants"],
+      keys=[<affected domain>, <affected paths>],
+      limit=5,
+  )
+  ```
+
+  A product rule is an intentional business constraint
+  (e.g., "free plan caps at 3 users"); the feature must either respect
+  it or explicitly propose to retire it. Cite the matching `id:` in
+  the findings. Schema:
+  [`engineering-memory-data-format`](../../guidelines/agent-infra/engineering-memory-data-format.md).
+
+**If contradiction found** → show the existing pattern, explain why it matters.
+
+### 4. Check for scope creep
+
+Evaluate if the request is:
+- Bigger than it appears (hidden complexity, many affected files)
+- Under-specified (missing error handling, edge cases, validation)
+- Over-engineered (complex solution for simple problem)
+
+**If scope concern** → quantify the impact (est. files, est. complexity).
+
+### 5. Present findings
+
+Format as a clear, concise summary:
+
+```
+## Feature Fit Analysis: [Feature Name]
+
+### ✅ Fits well
+- [What aligns with the codebase]
+
+### ⚠️ Concerns
+- [Concern 1 — with file reference]
+- [Concern 2 — with evidence]
+
+### Recommendation
+> 1. Proceed as-is
+> 2. Adjust approach — [brief suggestion]
+> 3. Discuss further
+```
+
+## Output format
+
+Always end with numbered options. The user should be able to reply with just a number.
+
+## Gotchas
+
+- Don't spend more than 2 minutes on this analysis — quick scan, not deep audit
+- Don't block work — if no clear issues found, say "looks good" and proceed
+- Don't challenge every request — only when there's actual evidence of misfit
+- Don't nitpick — focus on structural/architectural concerns, not style
+
+## Do NOT
+
+- Do NOT refuse to implement after the user made their choice
+- Do NOT repeat concerns the user already addressed
+- Do NOT make this analysis visible when there are no concerns
+- Do NOT run this on bug fixes, config changes, or trivial tasks
+- Do NOT use this as a reason to delay work