@event4u/agent-config 5.10.1 → 6.1.0

package/dist/agent-src/commands/condense.md

@@ -0,0 +1,240 @@
+---
+model_tier: medium
+name: condense
+pack: meta
+intent: "Condense src/ sources into the shipped dist/agent-src trees"
+routes_to: [skill-management]
+replaces: []
+tier: 1
+visibility: advanced
+skills: []
+description: Condense .md files from src/ into telegraph format and write to dist/agent-src/
+suggestion:
+  eligible: false
+  rationale: "Package-internal tooling; only the event4u/agent-config repo runs this."
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# condense
+
+Condense agent config `.md` files from `src/` into token-efficient telegraph format
+and write the condensed output to `dist/agent-src/`.
+
+Uses SHA-256 hashes to track which source files changed since last condensation.
+Only changed files need recondensation — saving tokens and time.
+
+## Step 1: Sync non-.md files
+
+```bash
+bash scripts/condense.sh --sync
+```
+
+This copies non-`.md` files (`.php`, etc.), deletes stale files, and shows the count of
+changed `.md` files that need condensation.
+
+## Step 2: Get changed files
+
+```bash
+bash scripts/condense.sh --changed
+```
+
+This lists only `.md` files whose source has changed since the last condensation (based on
+stored SHA-256 hashes). If no files changed → you're done.
+
+If you need to see ALL files regardless of change status:
+`bash scripts/condense.sh --list`.
+
+## Step 3: Condense each changed .md file
+
+**Core principle:** Condensation must improve execution quality, not just reduce length.
+A condensed file should be easier to scan, easier to trigger, and easier to execute than the original.
+
+For each changed `.md` file:
+
+1. Read the source from `src/{path}`
+2. Condense the prose using these rules:
+   - **Remove:** articles (a, an, the), filler (just, really, basically, actually, simply, essentially),
+     pleasantries, hedging, connective fluff (however, furthermore, additionally),
+     redundant wording, obvious framework knowledge, repeated explanations, decorative prose
+   - **Shorten:** "in order to" → "to", "make sure to" → "ensure", use short synonyms
+   - **Abbreviate** common terms when context is unambiguous: `DB`, `auth`,
+     `config`, `req`, `res`, `fn`, `impl`, `env`, `deps`, `ctx`. Skip if it
+     would be the first occurrence of the concept in the file, or if the
+     abbreviation collides with a domain term (e.g. `auth` stays
+     `authentication` inside an auth-module file). Never abbreviate inside
+     code blocks, frontmatter, file paths, command strings, or Iron Law
+     fenced blocks.
+   - **Arrows for causality:** `X causes Y` / `X leads to Y` / `X, then Y`
+     → `X → Y`. Keep arrows out of code blocks, frontmatter, and Iron Law
+     fenced blocks; only the surrounding prose uses them. (The example
+     phrases here are intentionally backticked so the inline-code
+     protection skips them — never strip those backticks.)
+   - **Fragments OK:** "Run tests before commit" not "You should always run tests before committing"
+   - **Drop:** "you should", "make sure to", "remember to" — state action directly
+   - **Merge** redundant bullets that say the same thing differently
+   - **Prefer** bullets over prose, direct instructions over explanatory paragraphs, one-line decisions over paragraphs
+3. **Copy-paste first, condense second:**
+   Before condensing ANY prose, extract and set aside these elements from the source.
+   They go into the condensed output **unchanged, byte-for-byte**:
+   - **All code blocks** (``` fenced or indented) — copy EVERY code block from source to output FIRST
+   - **YAML frontmatter** — copy verbatim
+   - **All inline code** (`backtick content`)
+   - **All URLs, links, file paths, commands**
+   - **All H1/H2 headings** — exact text preserved
+   - **Tables** (structure preserved, condense cell text only)
+   - **Technical terms, library names, API names**
+   - **Dates, version numbers, numeric values**
+   Then condense ONLY the prose around these preserved elements.
+4. **NEVER remove (even if verbose):**
+   - Trigger clarity (When to use / description)
+   - Decision hints that prevent mistakes
+   - Concrete validation checks
+   - Gotchas based on real failure patterns
+   - Anti-patterns that prevent recurring failures
+   - **Iron Law sections** — see "Iron Laws — do not touch" below
+5. **Enrich (SKILL.md files only):** During condensation, also improve agent-effectiveness:
+   - **Validation steps:** If a Procedure ends with a vague validation ("check if it works"),
+     replace with concrete checks (expected output, commands to verify, specific conditions)
+   - **Mini examples:** If no `Examples` section exists, add a short safe/unsafe or good/bad example
+     (2-4 lines max — not a tutorial)
+   - **Output format:** If the Output format section is vague ("explain everything"), sharpen it to
+     specific numbered expectations ("1. Code snippet 2. Where to register 3. Gotcha if relevant")
+   - **Anti-patterns:** If the same mistake keeps recurring, add a short anti-patterns section
+   - **Do NOT invent content.** Only concretize what the source implies. If the source says
+     "validate copy/paste safety", you can add "Check: no nested backticks, fully selectable".
+     But don't add unrelated sections.
+   - **Do NOT condense weak skills.** If the source has no procedure or no validation, fix structure first.
+   - **Reference skill:** See `src/skills/skill-writing/SKILL.md` for the gold standard
+6. Write the condensed output to `dist/agent-src/{path}`
+7. **MANDATORY: Run condensation quality check on this file:**
+
+```bash
+python3 scripts/check_condensation.py --format text 2>&1 | grep "{path}"
+```
+
+If the output contains 🔴 (error) for this file: **STOP. Fix the condensed file before continuing.**
+Common errors and how to fix them:
+- `lost_code_blocks` → You dropped a code block. Copy ALL code blocks from source.
+- `modified_code_block` → Code block content changed. Replace with exact source content.
+- `frontmatter_mismatch` → YAML frontmatter differs. Copy verbatim from source.
+
+**Do NOT call `mark-done` until this file has zero 🔴 errors.**
+
+8. Show word count: `{original} → {condensed} words ({saved}% saved)`
+9. **Mark as done:** `bash scripts/condense.sh --mark-done {path}`
+
+### Batch processing
+
+When condensing multiple files, process them in batches of ~10.
+Mark each file done after writing it. After each batch, show a progress summary:
+
+```
+Batch 1/5 complete: 10 files, avg 42% saved
+```
+
+## Step 4: Final verification gate
+
+Run BOTH checks. Both must pass before finishing.
+
+```bash
+bash scripts/condense.sh --check
+```
+
+Must show ✅ (hashes in sync).
+
+```bash
+python3 scripts/check_condensation.py
+```
+
+Must show **zero 🔴 errors**. Warnings (🟡) are acceptable.
+If any 🔴 errors remain: go back and fix those files before finishing.
+
+## Step 5: Summary (verbosity-gated)
+
+Read `verbosity.post_action_reports` from `.agent-settings.yml` (default
+`minimal`).
+
+- `off` → emit nothing on success; surface errors only.
+- `minimal` (default) → one line: `→ N files condensed (avg X% savings)`.
+- `full` → multi-line table with per-category stats (files condensed,
+  avg savings).
+
+## Hash management
+
+- Hashes are stored in `.augment/.condensation-hashes.json` (committed to Git).
+- `bash scripts/condense.sh --sync` automatically cleans up hashes for deleted source files.
+- `bash scripts/condense.sh --mark-all-done` marks ALL current `.md` files as condensed
+  (useful after an initial full condensation or when bootstrapping the hash file).
+- A file with no stored hash is always treated as "changed".
+
+## Iron Laws — do not touch
+
+Sections under headings matching `Iron Law`, `Iron Laws`, or `The Iron Law` (any
+heading level, numbered variants like `Iron Law 1` included) are **load-bearing
+behavioral rules**. Condensation rules above do **not** apply to them.
+
+For every Iron Law section in a source file:
+
+- **Copy the heading verbatim**, exact text, exact `#` level. NEVER downgrade
+  `## Iron Law` to `### Iron Law` or to inline `**Iron Law:**`.
+- **Copy the fenced code block byte-for-byte**, including capitalization, line
+  breaks, and trailing punctuation.
+- **Copy the negation clauses verbatim** — `NO X`, `NEVER Y`, `NOT Z`. These
+  are the law's exception denials; stripping them weakens the rule.
+- **Telegraph the prose, keep every passage** — every paragraph, every list
+  item, and every fenced code block from the source must appear in the
+  condensed output, in order. Drop articles, shorten phrasing, primitive
+  grammar, terse cave-speak — all encouraged. What's forbidden is dropping
+  whole sentences, merging two paragraphs into one, or skipping a bullet.
+  One paragraph → one paragraph; one bullet → one bullet.
+- **No word-count budget** — condense the prose as hard as telegraph style
+  allows. The check is structural (passage count), not quantitative.
+
+`scripts/check_condensation.py` enforces these mechanically — `iron_law_missing`,
+`iron_law_passage_dropped`, and `iron_law_heading_downgrade` are `error`-level
+and block CI.
+
+If an Iron Law section genuinely contains filler (rare): edit the SOURCE in
+`src/`, not the condensed copy. Source is the truth.
+
+## Condensation quality checklist
+
+**Also apply the `preservation-guard` rule** — strongest validation, example, anti-pattern, and decision hints must survive condensation. Iron Laws are non-negotiable.
+
+After condensing each file, verify:
+
+- [ ] All code blocks preserved exactly (no content changes)
+- [ ] All inline code, URLs, file paths unchanged
+- [ ] YAML frontmatter identical to source
+- [ ] Headings match source exactly
+- [ ] Tables structure preserved (cell text may be shortened)
+- [ ] "NEVER", "MUST", "Do NOT" and other strong language preserved
+- [ ] Technical terms, library names, API names unchanged
+- [ ] No meaning lost — condensed version says the same thing, shorter
+- [ ] No sections accidentally removed
+- [ ] Word count reduction is 20-50% (typical range for prose-heavy files)
+
+### Safe vs unsafe condensation
+
+Safe:
+- "You should always make sure to run the tests before committing" → "Run tests before commit"
+- "In order to ensure that the configuration is correct" → "To verify config"
+- "It is important to note that this feature requires" → "Requires"
+
+Unsafe (DO NOT do this):
+- Removing a bullet point that contains unique information
+- Changing `php artisan test --filter=MyTest` to `php artisan test`
+- Shortening "Do NOT use float for money" to "Avoid float"
+- Removing "NEVER" from "NEVER add to phpstan-baseline.neon"
+
+## Rules
+
+- **Do NOT commit or push.** Only write files.
+- **Do NOT modify `src/`** — it is the source of truth.
+- **Only write to `.augment/`** — the condensed output directory.
+- **Preserve ALL technical content** — only condense natural language prose.
+- **YAML frontmatter** in command/skill files must be preserved exactly.
+- **Always run `bash scripts/condense.sh --mark-done {path}`** after writing each condensed file.

package/dist/agent-src/commands/context/create.md

@@ -0,0 +1,182 @@
+---
+model_tier: inherit
+name: context-create
+pack: meta
+tier: 2
+visibility: internal
+cluster: context
+sub: create
+skills: [agent-docs-writing]
+description: Analyze a codebase area and create a structured context document
+suggestion:
+  eligible: true
+  trigger_description: "document this part of the codebase, create a context doc for X"
+  trigger_context: "working in a module without an agents/settings/contexts/ doc"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /context create
+## Instructions
+
+### 1. Ask what to document
+
+If the user provided a topic, use it. Otherwise ask:
+
+```
+📄 What area do you want to document?
+
+Examples:
+- A module (e.g. "ClientSoftware Module")
+- A service (e.g. "CustomerService and Tenant-Switching")
+- An integration (e.g. "ProBauS API Integration")
+- A domain area (e.g. "Import pipeline from upload to processing")
+- Infrastructure (e.g. "Queue system with Horizon")
+```
+
+### 2. Determine scope (module vs. project-wide)
+
+Resolve module roots via `scripts/_lib/agent_settings.py::enumerate_modules()`
+(reads `modules.root_paths` + `modules.agent_folder` from
+`.agent-project-settings.yml`). If at least one module is discovered, ask:
+
+```
+Should the context be created in a module or in the project root?
+
+1. 📦 In a module → {module_root}/{Module}/{agent_folder}/settings/contexts/
+2. 🌐 Project root → agents/settings/contexts/
+```
+
+If module:
+- Render the list of modules from `enumerate_modules()` and ask which one.
+- Target: `{module_root}/{Module}/{agent_folder}/settings/contexts/`
+  (Laravel example: `app/Modules/{Module}/agents/settings/contexts/`)
+- Create directory if it doesn't exist.
+
+If project-wide:
+- Target: `agents/settings/contexts/`
+
+### 3. Determine context type
+
+```
+What type of context is this?
+
+1. 📦 Module — structure and purpose of a module
+2. 🏢 Domain — business logic across multiple modules
+3. ⚙️ Service — complex service with dependencies
+4. 🔗 Integration — external API/system integration
+5. 🏗️ Infrastructure — DevOps, infrastructure
+```
+
+### 4. Analyze the code
+
+Based on the type, analyze the relevant code area:
+
+**Module context:**
+- List all directories and file counts
+- Read key services, controllers, models
+- Analyze route files
+- Check for tests, agent docs
+
+**Domain context:**
+- Search across modules for related code
+- Trace data flow through services
+- Identify all models and tables involved
+
+**Service context:**
+- Read the service class and its deps
+- Trace call chain (who calls it, what it calls)
+- Identify configuration and env deps
+
+**Integration context:**
+- Find API client classes, HTTP calls
+- Read config for credentials/URLs
+- Identify error handling and retry logic
+
+**Infrastructure context:**
+- Read config files, Docker setup
+- Identify services and their connections
+- Check monitoring/logging setup
+
+**Share findings as you go:**
+```
+🔍 Ich analysiere den Code...
+
+Gefunden:
+  • 5 Services in App/Services/
+  • 3 Controllers mit 12 API Endpoints
+  • 8 Models mit Beziehungen zu customer_database
+  • 42 Tests (15 Unit, 20 Component, 7 Integration)
+
+Should I investigate any specific areas in more detail?
+```
+
+### 5. Interactive refinement
+
+After analysis, discuss findings:
+
+- "I noticed {Service} depends on {Dependency}. Is that correct?"
+- "There are {count} endpoints — should all be documented?"
+- "Are there known issues or technical debt in this area?"
+- "Anything I missed?"
+
+### 6. Create the context document
+
+- Read `.augment/templates/contexts.md` for the structure.
+- Create the context file in the target directory.
+- Fill in all applicable sections from the analysis.
+- Set `Last Updated` to today's date.
+
+**Ask for the filename:**
+```
+Context name?
+
+> 1. {suggested-kebab-case-name} (suggested)
+> 2. Enter a custom name
+
+Target: {target-directory}/{name}.md
+```
+
+### 7. Show result
+
+```
+═══════════════════════════════════════════════
+  ✅  CONTEXT CREATED
+═══════════════════════════════════════════════
+
+📄 {path/to/context.md}
+📊 Typ: {type}
+📦 Module: {module or "project-wide"}
+
+───────────────────────────────────────────────
+INHALT:
+───────────────────────────────────────────────
+
+  Key Files:       {count}
+  Key Classes:     {count}
+  DB Tables:       {count}
+  API Endpoints:   {count}
+  Known Issues:    {count}
+
+═══════════════════════════════════════════════
+```
+
+### 8. Offer next steps
+
+```
+What's next?
+
+1. ✏️ Adjust context → /context-refactor
+2. 📋 Plan a feature based on this context → /feature-plan
+3. ✅ Done
+```
+
+### Rules
+
+- **Do NOT commit or push.**
+- **Always analyze the code first** — never guess or assume.
+- **Be factual** — document what IS, not what SHOULD be.
+- **Ask the user** about unclear areas or business context.
+- **Link to specific files** — not vague descriptions.

package/dist/agent-src/commands/context/refactor.md

@@ -0,0 +1,184 @@
+---
+model_tier: high
+name: context-refactor
+pack: meta
+tier: 2
+visibility: internal
+cluster: context
+sub: refactor
+skills: [agent-docs-writing]
+description: Analyze, update, and extend an existing context document
+suggestion:
+  eligible: true
+  trigger_description: "update the context doc, refresh this context document"
+  trigger_context: "existing agents/settings/contexts/*.md referenced in the prompt"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /context refactor
+## Instructions
+
+### 1. Find the context
+
+- List all context documents in `agents/settings/contexts/`.
+- Also check module-level contexts via `enumerate_modules()` — for each
+  module, look in `{module_path}/{modules.agent_folder}/settings/contexts/`
+  (Laravel shape: `app/Modules/*/agents/settings/contexts/`).
+
+If only one context exists, ask if that's the one to refactor.
+If the user has a context file open in their editor, use that one.
+If multiple exist, show a list:
+
+```
+📂 Existing context documents:
+
+  #  Name                    Ort                  Typ            Letzte Aktualisierung
+  ─  ──────────────────────  ───────────────────  ─────────────  ─────────────────────
+  1  client-software.md      Modul: ClientSoftware Module        2026-03-15
+  2  import-pipeline.md      Projekt-Root          Domain        2026-03-10
+  3  probaus-api.md          Projekt-Root          Integration   2026-02-28
+
+Which context do you want to update? (number or name)
+```
+
+If no contexts exist:
+```
+ℹ️  No context documents found. Create one first with /context-create.
+```
+Stop.
+
+### 2. Load and display the context
+
+- Read the selected context file completely.
+- Display a summary:
+
+```
+═══════════════════════════════════════════════
+  ✏️  CONTEXT: {title}
+═══════════════════════════════════════════════
+
+📊 Typ:              {type}
+📅 Last updated:     {last updated}
+📦 Module:           {module or "project-wide"}
+
+───────────────────────────────────────────────
+CURRENT CONTENT:
+───────────────────────────────────────────────
+
+  Key Files:       {count}
+  Key Classes:     {count}
+  DB Tables:       {count}
+  API Endpoints:   {count}
+  Known Issues:    {count}
+
+═══════════════════════════════════════════════
+```
+
+### 3. Re-analyze the code
+
+Re-analyze the documented area to find changes:
+
+- Check if documented files still exist.
+- Look for new files/classes that aren't documented.
+- Verify database tables and endpoints are still accurate.
+- Check for new tests.
+
+**Show findings:**
+
+```
+🔍 Re-analysis complete:
+
+  ✅  Still current:
+    • ImportService — unchanged
+    • 8 Models — all present
+
+  ⚠️  Outdated / changed:
+    • ProcessImportCommand — new parameters added
+    • ImportUploadType — 2 new enum values
+
+  🆕 New (not documented):
+    • ImportValidationService (newly added)
+    • api/v1/imports/validate endpoint
+
+  ❌  Removed:
+    • OldImportHelper — no longer exists
+```
+
+### 4. Ask what to do
+
+```
+What do you want to adjust?
+
+1. 🔄 Auto-update everything (based on the analysis)
+2. ✏️ Manually edit specific sections
+3. ➕ Add new areas
+4. 🗑️ Remove outdated entries
+5. 💬 Something else
+```
+
+**Option 1 — Auto-update:**
+- Remove entries for deleted files/classes.
+- Add entries for new files/classes.
+- Update changed entries.
+- Show all changes for confirmation before applying.
+
+**Option 2 — Manual edit:**
+Show section list:
+```
+Which section?
+
+1. Overview
+2. Key Files
+3. Key Classes & Services
+4. Database
+5. API Endpoints
+6. Dependencies
+7. Patterns & Conventions
+8. Known Issues / Technical Debt
+9. Notes
+```
+
+**Option 3 — Add new areas:**
+- Ask what to add.
+- Analyze the relevant code.
+- Add new sections or entries.
+
+### 5. Apply changes
+
+- Update the context file.
+- Update `Last Updated` to today's date.
+- Show a diff summary:
+
+```
+───────────────────────────────────────────────
+CHANGES:
+───────────────────────────────────────────────
+
+  🆕 Added: 3 Key Files, 1 Service, 1 Endpoint
+  ✏️ Updated: 2 Classes, 1 Known Issue
+  🗑️ Removed: 1 obsolete service
+  📅 Last Updated: 2026-03-20
+```
+
+### 6. Ask for additions
+
+```
+Anything else to add?
+
+1. ➕ Yes — document another area
+2. 🔍 Investigate a specific class/service in detail
+3. ✅ No, done
+```
+
+If option 1 or 2 → loop back to analysis and update.
+
+### Rules
+
+- **Do NOT commit or push.**
+- **Always re-analyze the code** before updating — don't just edit text.
+- **Show changes before applying** — the user should confirm.
+- **Preserve user-written notes and context** — don't overwrite manual additions.
+- **Update `Last Updated`** after every change.

package/dist/agent-src/commands/context.md

@@ -0,0 +1,53 @@
+---
+model_tier: medium
+name: context
+disable-model-invocation: true
+pack: meta
+tier: 2
+visibility: internal
+description: Context orchestrator — routes to create, refactor
+cluster: context
+type: orchestrator
+suggestion:
+  eligible: true
+  trigger_description: "create a context document, update an existing context, refactor a context file"
+  trigger_context: "user wants to author or restructure a context document"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /context
+
+Top-level orchestrator for the `/context` family. Replaces 2 standalone
+commands with a single entry point + sub-command dispatch.
+
+## Sub-commands
+
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+| `/context create` | `commands/context/create.md` | Analyze a codebase area and create a structured context document |
+| `/context refactor` | `commands/context/refactor.md` | Analyze, update, and extend an existing context document |
+
+Sub-command names match the locked contract in
+[`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
+
+## Dispatch
+
+1. Parse the user's argument: `/context <sub-command> [args]`.
+2. Look up the sub-command in the table above.
+3. Load the body of the routed file and follow its `## Instructions` section
+   verbatim with the remaining args.
+4. If the sub-command is unknown or missing, print the table above and ask:
+
+   > 1. create — author a new context document
+   > 2. refactor — update an existing context document
+
+## Rules
+
+- **Do NOT commit, push, or open a PR** unless the sub-command explicitly
+  authorizes it.
+- **Do NOT chain sub-commands.** One `/context <sub>` per turn.
+- If the user invokes `/context` with no argument, **show the menu** — do
+  not guess which sub-command they meant.