@event4u/agent-config 1.9.1

package/.agent-src/skills/skill-improvement-pipeline/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: skill-improvement-pipeline
+description: "ONLY when user explicitly requests: run the skill improvement pipeline after a learning was detected. Orchestrates capture, classify, create, validate, and apply."
+source: package
+execution:
+  type: assisted
+  handler: internal
+  allowed_tools: []
+---
+
+# skill-improvement-pipeline
+
+## When to use
+
+- Triggered by the `skill-improvement-trigger` rule when user picks "Capture & improve"
+- Manually when user says "run the improvement pipeline" or "capture this learning"
+
+Do NOT use for:
+- Regular skill creation (use `skill-writing`)
+- Regular skill editing (use `skill-management`)
+- One-off fixes that don't represent a pattern
+
+## Procedure: Run the improvement pipeline
+
+### Step 1: Capture
+
+Use the `learning-to-rule-or-skill` skill to extract 1–3 concrete learnings from the completed task.
+
+Each learning must be:
+- **Specific** — not "be more careful" but "always check X before Y"
+- **Actionable** — can be turned into a rule constraint or skill step
+- **Observable** — you can tell when it's followed or violated
+
+### Step 2: Promotion Gate
+
+For each learning, apply ALL of these checks. ALL must be YES to promote:
+
+| Check | Question |
+|---|---|
+| Repeated? | Has this pattern occurred 2+ times, or is it clearly generalizable? |
+| Prevents failure? | Does it prevent a real observed failure or mistake? |
+| Not covered? | Is there NO existing rule or skill that already covers this? |
+| Actionable? | Is it a concrete constraint or workflow step (not vague advice)? |
+
+| Result | Action |
+|---|---|
+| All YES | **Promote** — continue to Step 3 |
+| One-off, never seen before | **Reject** — do nothing |
+| Seen once, but generalizable | **Note** — use `remember` tool, act on second occurrence |
+| Already covered | **Update existing** — skip to Step 4 with the existing skill/rule |
+| Vague | **Reject** — not actionable |
+
+Show the user:
+```
+> Learning: "{summary}"
+> Category: {category-tag}
+> Repeated: {yes/no} | Prevents failure: {yes/no} | Not covered: {yes/no} | Actionable: {yes/no}
+>
+> → {Promote / Reject / Note / Update existing}
+```
+
+### Step 3: Classify
+
+#### Category tag
+
+Tag each learning with one category for tracking:
+
+| Category | When |
+|---|---|
+| `skill-weakness` | Skill gave wrong or incomplete guidance |
+| `rule-weakness` | Rule was too vague or missed a case |
+| `routing-issue` | Wrong skill was selected for the task |
+| `assumption-issue` | Agent made bad assumptions instead of asking |
+| `verification-gap` | Verification step was missing or weak |
+| `optimization-overreach` | Optimize command suggested harmful change |
+
+#### Artifact type
+
+Decide what to create:
+
+| Learning type | Create |
+|---|---|
+| Behavioral constraint ("always do X", "never do Y") | **Rule** (auto-type) |
+| Workflow/procedure ("when X happens, do Y then Z") | **Skill** |
+| Existing rule/skill needs update | **Update** (use `skill-management`) |
+
+### Step 4: Create or Update
+
+- **New rule** → create in `.agent-src.uncompressed/rules/`, follow rule conventions
+- **New skill** → use `skill-writing` skill, create in `.agent-src.uncompressed/skills/`
+- **Update existing** → use `skill-management` skill
+
+After creation:
+1. Run `python3 scripts/skill_linter.py {path}` — must pass (0 fail)
+2. Copy to `.augment/`
+3. Mark hash: `python3 scripts/compress.py --mark-done "{relative_path}"`
+4. Regenerate tools: `python3 scripts/compress.py --generate-tools`
+
+### Step 5: Decide scope
+
+Ask the user:
+
+```
+> 📦 Improvement ready: {description}
+>
+> 1. Universal — apply locally + PR to upstream package
+> 2. Project-specific — apply locally only (agents/overrides/)
+> 3. Review first — show me the changes before deciding
+```
+
+### Step 6: Apply
+
+**If project-specific (option 2):**
+- Create override in `agents/overrides/{type}/{name}.md`
+- Done.
+
+**If universal (option 1):**
+1. Read `project.upstream_repo` and `project.improvement_pr_branch_prefix` from `.agent-settings.yml`
+2. If `project.upstream_repo` is empty → ask user for the target repo
+3. Create branch: `{prefix}{learning-slug}` from `main`
+4. Commit changes to `.agent-src.uncompressed/` AND `.augment/`
+5. Push branch
+6. Create PR with title: `improve(agent): {short description}`
+7. Use the agent-improvement PR template if it exists
+
+## Output format
+
+1. Learning summary with promotion gate results
+2. Created/updated file path
+3. Linter result
+4. Scope decision and action taken
+
+## Gotcha
+
+- The promotion gate is the most important step — most learnings should be REJECTED
+- "Be more careful" is NOT a valid learning — it must be specific
+- Always run the linter before declaring success
+- The user controls every step — never auto-commit or auto-push
+
+## Do NOT
+
+- Do NOT skip the promotion gate — it prevents skill/rule bloat
+- Do NOT create both a rule AND a skill for the same learning
+- Do NOT auto-push without user permission
+- Do NOT create project-specific content in `.agent-src.uncompressed/`
+- Do NOT run this pipeline for trivial learnings
+
+## References
+
+- **Reflexion** — [arxiv.org/abs/2303.11366](https://arxiv.org/abs/2303.11366)
+  Language agents that reinforce from verbal self-reflection on past
+  trials. This pipeline adapts Reflexion by gating promotion with a
+  human review step — learnings only harden into rules/skills after
+  explicit approval, never auto-commit.
+

package/.agent-src/skills/skill-management/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: skill-management
+description: "Use when compressing, decompressing, refactoring, or improving existing skills. Covers the full skill lifecycle from verbose → sharp → maintained."
+source: project
+execution:
+  type: assisted
+  handler: internal
+  allowed_tools: []
+---
+
+# skill-management
+
+## When to use
+
+Use this skill when:
+* Compressing a verbose skill into a sharper version
+* Expanding a compressed skill into a maintainable source-of-truth
+* Refactoring a skill to fix structure, scope, or quality issues
+* Migrating skills to new standards
+
+Do not use when:
+* Creating a new skill from scratch (use `skill-writing`)
+* Reviewing/validating a skill (use `skill-reviewer`)
+
+## Procedure: Manage a skill
+
+### Mode: Compress
+**Trigger:** "compress skill", "shorten skill", "make skill sharper"
+
+1. Inspect — what is the core job? Which lines are redundant?
+2. Preserve critical skeleton: When to use, Procedure, Output format, Gotchas, Do NOT
+3. Compress trigger — rewrite description for fast matching
+4. Compress decision logic — explanations → direct choices
+5. Compress procedure — each step short and executable
+6. Remove obvious content — keep only what model forgets or misuses
+7. Validate — compressed version must be: easier to scan, easier to trigger, at least as safe
+
+**Iron rule:** Compression must NOT weaken validation or remove decision hints that prevent mistakes.
+**Linter gate:** After compression, run `python3 scripts/skill_linter.py` on the file — must be 0 FAIL.
+
+### Mode: Decompress
+**Trigger:** "expand skill", "decompress skill", "make skill clearer"
+
+1. Inspect — which parts are unclear or too condensed?
+2. Restore full structure (all required sections)
+3. Expand trigger — make "When to use" clearer
+4. Expand procedure — turn terse steps into clear actions
+5. Strengthen validation — make checks explicit and testable
+6. Add minimal explanations only where they improve execution
+7. Validate — expanded version must be: clearer, still executable, not noisy
+
+**Iron rule:** Expansion must NOT turn skills into documentation. Add context, not prose.
+**Linter gate:** After expansion, run `python3 scripts/skill_linter.py` on the file — must be 0 FAIL.
+
+### Mode: Refactor
+**Trigger:** "refactor skill", "improve skill", "fix skill structure"
+
+1. Inspect — identify missing sections, weak areas, anti-patterns
+2. Clean structure — ensure required sections exist
+3. Improve procedure — make steps concrete, add validation
+4. Remove noise — delete obvious/redundant content, merge duplicate bullets
+5. Refine scope — ensure single responsibility, split if multiple workflows
+6. Compare before/after — must be clearer, at least as executable, not broader
+
+**Linter gate:** After refactoring, run `python3 scripts/skill_linter.py` on the file — must be 0 FAIL.
+
+**Independence check:** After refactoring, verify the skill is still executable without opening any guideline.
+If the refactor introduced guideline delegations ("see guideline X"), ensure the Procedure still works standalone.
+
+**Decision hints:**
+* Too long → compress or split
+* Too generic → narrow scope
+* Missing validation → add it
+* Too dependent on guidelines → inline essential steps
+* Multiple workflows → split into separate skills
+
+## Common anti-patterns
+
+* Same idea repeated in Goal, Core rules, and Gotchas
+* Long paragraphs where one bullet would do
+* Vague procedure steps ("think about X")
+* Compression that deletes safety-critical checks
+* Over-expansion that turns skills into documentation
+* Refactoring scope instead of structure
+* Removing gotchas because they "look verbose"
+
+## Output format
+
+1. Updated skill file(s) passing linter with 0 FAIL
+2. Before/after line count comparison
+
+## Gotchas
+
+* Over-compression removes important nuance
+* Some examples look verbose but are load-bearing
+* Shorter is not better if trigger quality drops
+* Changing intent instead of improving structure
+* Compressed versions must be derived from uncompressed source, not the other way around
+* **Validation steps are non-negotiable** — every Procedure must end with a concrete verify/confirm step. Skills without validation pass the linter today but cause failures when the linter is tightened.
+* **Renaming headings to "Procedure:" without adding steps** creates false structure — the linter now requires ordered steps or sub-headings inside Procedure blocks.
+
+## Do NOT
+
+* Do NOT remove validation steps
+* Do NOT compress away decision hints that prevent mistakes
+* Do NOT change the skill's core intent
+* Do NOT merge unrelated workflows to save space
+* Do NOT expand everything blindly — only where it helps execution
+* Do NOT rewrite without understanding original intent
+* Do NOT skip the `preservation-guard` rule checklist before completing any transformation
+
+## Auto-trigger keywords
+
+* compress skill
+* decompress skill
+* refactor skill
+* improve skill
+* shorten skill
+* expand skill
+* caveman compress
+* make skill sharper

package/.agent-src/skills/skill-reviewer/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: skill-reviewer
+description: "Use when reviewing, auditing, or optimizing skills — validates against the 7 Skill Killers checklist and produces fix recommendations."
+source: package
+execution:
+  type: assisted
+  handler: internal
+  allowed_tools: []
+---
+
+# Skill Reviewer
+
+## When to use
+
+Use when reviewing, auditing, or optimizing existing skills — checking quality against the 6 Skill Killers checklist. Also for validating a new skill before saving.
+
+Reviews skills against the **7 Skill Killers** — the most common anti-patterns
+that waste tokens, cause misfires, or degrade agent performance.
+
+## The 7 Skill Killers Checklist
+
+### Killer 1: Vague or Quiet Description
+
+The description is the **most critical line** — it's a trigger, not a summary.
+
+**Good pattern:**
+```yaml
+description: >
+  Use when the user says "create a DTO", "new data transfer object",
+  or asks to convert request/response data into a typed PHP class.
+  Also triggers on "map this to a DTO" or "I need a value object".
+  Creates DTO classes following project conventions with SimpleDto
+  base class, attribute mapping, and validation.
+```
+
+**Bad patterns:**
+- ❌  `"Creates DTO classes following project conventions"` — no trigger phrases
+- ❌  `"Handles DTOs"` — too vague, won't fire
+- ❌  Only describes WHAT, never WHEN
+
+**Fix rules:**
+- Start with `Use when the user says "..."` or `Use when [situation]`
+- Include 3-5 trigger phrases people actually say
+- Write in third person (injected into system prompt)
+- Be LOUD — models skip past quiet descriptions
+- End with 1 sentence describing what the skill does
+- For explicit-only skills: `"ONLY when user explicitly requests: [X]. NOT for [Y]."`
+
+### Killer 2: Over-Defining (Railroading)
+
+The skill dictates every micro-step instead of guiding.
+
+**Check:** Are there >15 numbered steps? Does it prescribe HOW to think?
+**Fix:** Set degrees of freedom — tight for fragile ops (migrations, deployments),
+loose for creative tasks (design, planning). Use bullets over numbered steps
+when order doesn't matter.
+
+### Killer 3: Stating the Obvious
+
+Content the model already knows — wasting tokens on every invocation.
+
+**Check:** For each paragraph, ask: "Does the model really need this?"
+**Examples of waste:**
+- ❌  Explaining what PHP strict types do
+- ❌  Describing how Laravel middleware works (in a middleware skill)
+- ❌  Listing basic Git commands
+
+**Keep only:** Project-specific conventions, non-obvious patterns, YOUR way of doing things.
+
+### Killer 4: Missing Gotcha Section
+
+The highest-signal content in a skill. Documents failure patterns.
+
+**Check:** Does the skill have a `## Gotcha` or `## Common Mistakes` section?
+**Fix:** Add one with real failure patterns:
+```markdown
+## Gotcha
+
+- Don't assume X — check Y first because Z
+- The model tends to forget A when doing B
+- Edge case: when C happens, do D instead of E
+```
+
+### Killer 5: Monolithic Blob
+
+Skill exceeds size limits (see `guidelines/agent-infra/size-and-scope.md`).
+
+**Check:** Review at >300 lines. Strongly consider split at >1200 words / >1500 words.
+**Fix:** Extract reference tables, templates, and examples into separate files
+in the skill folder, or split by responsibility.
+
+### Killer 6: Guideline-Dependent (Pointer-Only)
+
+The skill delegates to guidelines instead of containing its own executable workflow.
+
+**Iron Rule:** If a skill is not executable without opening a guideline, it is broken.
+
+**Check:** Cover all guideline references in the skill — is the Procedure still executable?
+**Litmus test:** Remove `→ See guideline ...` lines. Does the skill still tell the agent what to do?
+
+**Fail if:** ≥3 guideline delegations AND ≤1 action verb AND <3 procedure steps
+**Warn if:** ≥2 guideline delegations AND ≤2 action verbs AND <3 procedure steps
+
+**Fix:** Inline the essential workflow steps from the guideline. Keep the guideline reference
+for deep-dive details, but the Procedure must work standalone.
+
+### Killer 7: Created Without Analysis
+
+The skill/rule/command was written without inspecting existing state or defining expected behavior.
+
+**Check:** Was the artifact created based on:
+- Reading the existing implementation or related artifacts?
+- Comparing with current behavior, tests, or requirements?
+- Defining expected behavior before writing?
+- Using targeted tools for investigation?
+
+**Fail or warn if:**
+- No evidence of inspecting existing state before creating/refactoring
+- Looks like blind trial-and-error or copy-paste-and-hope
+- Expected behavior is only implied, never explicitly stated
+- Refactor made artifact cleaner but weaker (lost validation, examples, or gotchas)
+- Requirements were ambiguous but no clarification was sought
+
+**Fix:** Add analysis step, define expected outcome, verify with linter/tests, restore any lost content.
+
+## Pre-check: Should this be a skill at all?
+
+Before scoring the 5 Killers, ask: **Does this belong as a skill?**
+
+| If the content is... | Verdict |
+|---|---|
+| Standard tool usage (jq, docker exec, git commands) | ❌ **Not a skill** — baseline model knowledge |
+| Single-command operations without decision logic | ❌ **Not a skill** — too thin for a workflow |
+| Always-true constraint ("never X", "always Y") | ❌ **Not a skill** — should be a Rule |
+| Coding conventions / reference material | ❌ **Not a skill** — should be a Guideline |
+| Step-by-step workflow with decisions and validation | ✅ **Skill** — proceed with review |
+| Error-prone process that models get wrong without guidance | ✅ **Skill** — even if steps seem simple |
+
+If the skill fails this pre-check → recommend: migrate (rule/guideline), absorb (into existing skill), or delete.
+
+## Structural Validation (pre-review)
+
+Before scoring the 5 Killers, verify structure:
+
+**Skills** — required sections:
+- When to use (with "Do not use when")
+- Procedure (numbered steps OR `###` sub-headings — NOT just a renamed heading with prose)
+- Concrete validation step inside Procedure (must contain: verify, confirm, must pass, run test, etc.)
+- Gotchas
+- Do NOT
+
+**Linter:** Run `python3 scripts/skill_linter.py` on any skill after review — must be 0 FAIL.
+
+**Rules** — must be:
+- Short and directive
+- Always-applicable (no situational triggers)
+- Not procedural (no numbered steps — that's a skill)
+
+**Compression safety** (if compressed version exists):
+- Trigger clarity preserved
+- Decision hints or equivalent present
+- Concrete validation still present
+- Gotchas/anti-failure protection retained
+
+**Merge/refactor safety** (if reviewing a merge, refactor, or restructuring):
+- Apply `preservation-guard` rule checklist
+- Strongest validation, example, and anti-pattern must survive
+- Scope must not broaden from merging unrelated concerns
+- Strong language must not be weakened
+
+**Scope check:**
+- No overlap with existing skill or rule (name + description)
+- Single workflow per file (multiple workflows → split)
+- Update existing preferred over creating new file
+
+## Procedure: Review a skill
+
+### Single skill
+1. Validate structure (required sections present)
+2. Score each killer: ✅ Pass / ⚠️ Weak / ❌ Fail
+3. Check compression safety (if applicable)
+4. Produce a verdict table + specific fix suggestions
+
+### Batch audit
+1. Scan all skills in `.augment/skills/`
+2. For each: check description format, line count, gotcha presence
+3. Produce a summary table sorted by severity
+4. Group fixes by type (e.g., "these 20 need description rewrites")
+
+## Output Format
+
+```markdown
+| Skill | K1 Desc | K2 Over | K3 Obvious | K4 Gotcha | K5 Size | K6 Pointer | K7 Analysis | Verdict |
+|---|---|---|---|---|---|---|---|---|
+| dto-creator | ❌ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | Fix description |
+```
+
+## Output format
+
+1. Review report with pass/fail per checklist item
+2. Prioritized fix recommendations
+
+## Gotcha
+
+- Don't rewrite skills unnecessarily — only fix actual killer violations.
+- A description that works (triggers correctly) is fine even if not perfect.
+- Gotcha sections grow organically — seed them, don't force 10 entries.
+- "Stating the obvious" is relative to the MODEL, not to junior developers.
+  If the model consistently gets something wrong, it's NOT obvious — keep it.
+- Skills under 50 lines rarely have Killer 5 problems — skip that check.
+- Flag any "Related skills" section — the agent discovers skills via `<available_skills>` descriptions. Cross-links waste tokens and create maintenance burden. Recommend removal.
+
+
+## Do NOT
+
+- Do NOT rewrite skills that pass all 7 killers — leave them alone.
+- Do NOT add "Related skills" cross-links — the agent discovers via descriptions.
+- Do NOT force Gotcha entries — seed naturally from real failures.