@event4u/agent-config 1.20.0 → 1.21.0

package/.agent-src/commands/agents.md

@@ -23,7 +23,7 @@ commands with a single entry point + sub-command dispatch.
 | `/agents prepare` | `commands/agents/prepare.md` | Scaffold the `agents/` directory structure |
 
 Sub-command names match the locked contract in
-[`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+[`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
 
 ## Dispatch
 

package/.agent-src/commands/bug-fix.md

@@ -182,4 +182,4 @@ What next?
 
 ## See also
 
-- [`role-contracts`](../../docs/guidelines/agent-infra/role-contracts.md#developer) — Developer mode output contract (Goal / Plan / Changes / Tests / Open questions)
+- [`role-contracts`](../docs/guidelines/agent-infra/role-contracts.md#developer) — Developer mode output contract (Goal / Plan / Changes / Tests / Open questions)

package/.agent-src/commands/bug-investigate.md

@@ -175,5 +175,5 @@ What's next?
 
 ## See also
 
-- [`role-contracts`](../../docs/guidelines/agent-infra/role-contracts.md#incident) — Incident mode output contract (Symptom / Reproduction / Minimal reversible change / Deferred verification / Follow-up commitment) — use when the bug is a live production issue with `break-glass: true`
-- [`role-contracts`](../../docs/guidelines/agent-infra/role-contracts.md#developer) — Developer mode output contract for non-incident bugs
+- [`role-contracts`](../docs/guidelines/agent-infra/role-contracts.md#incident) — Incident mode output contract (Symptom / Reproduction / Minimal reversible change / Deferred verification / Follow-up commitment) — use when the bug is a live production issue with `break-glass: true`
+- [`role-contracts`](../docs/guidelines/agent-infra/role-contracts.md#developer) — Developer mode output contract for non-incident bugs

package/.agent-src/commands/chat-history/import.md

@@ -2,31 +2,30 @@
 name: chat-history:import
 cluster: chat-history
 sub: import
-description: Surface prior chat-history sessions as numbered options, let the user pick exactly one, then render its entries verbatim into the current chat — selective, user-driven cross-session import
+description: Surface prior chat-history sessions as a numbered table, let the user pick one, read it silently, and emit a short summary plus a resume offer — selective, user-driven cross-session import
 disable-model-invocation: true
 suggestion:
   eligible: true
   trigger_description: "import a past session into the current chat, pull a prior session into context, pick a session to read"
-  trigger_context: "user wants to selectively pull verbatim context from one earlier session into the current one"
+  trigger_context: "user wants to selectively pull a prior session's context into the current one as a short summary"
 ---
 <!-- cloud_safe: noop -->
 
 # /chat-history import
 
 Read-only, **user-driven** cross-session import. Surfaces prior
-sessions logged in `agents/.agent-chat-history` as numbered options, the
-user picks **one**, the agent reads that session's entries
-**verbatim** and renders them in the chat. Any subsequent
-extraction or summarisation happens in dialogue, user-directed —
-the agent does **not** auto-summarise, auto-import, or rewrite the
-user's context (Council Round 2 / R2-2 — verbatim is the honest v1
-contract).
+sessions logged in `agents/.agent-chat-history` as a numbered table,
+the user picks **one**, the agent reads that session **silently**
+and emits a 2–5 sentence summary, then offers to resume the last
+task from that session. The agent does **not** render entries
+verbatim, auto-import, or rewrite the user's context without an
+explicit instruction.
 
 This is the opt-in counterpart to the read-path filter (Phase 3 of
 `road-to-chat-history-session-isolation`): default reads stay
 session-scoped; `import` is the explicit surface for crossing the
-session boundary verbatim. For project-improving learnings derived
-from a prior session, see [`/chat-history learn`](learn.md).
+session boundary. For project-improving learnings derived from a
+prior session, see [`/chat-history learn`](learn.md).
 
 ## When NOT to use
 
@@ -70,33 +69,35 @@ If the array is empty, stop:
 > 📒 No prior sessions found in agents/.agent-chat-history.
 ```
 
-### 3. Surface as numbered options
+### 3. Surface as a numbered table
 
-Render each session as a numbered option (per the `user-interaction`
-rule — Iron Law: numbered options for any picker). Lead with the
-helper's `summary` field — that is the rough arc the user picks by
-(`<first user msg> → <last user msg>` for normal sessions, or
-`(N entries — no user prompts; t-mix: …)` for tool-only sessions).
-The session `id` is noise to humans; keep it **internal** for step
-5's `read --session <id>` call and never render it in the listing.
+Render the sessions as a markdown table — the row number is the
+option (per `user-interaction` Iron Law: numbered options for any
+picker). The session `id` is noise to humans; keep it **internal**
+for step 5's `read --session <id>` call and never render it.
 Format:
 
 ```
-> Pick a session to import verbatim:
->
-> 1. {summary}
->    {YYYY-MM-DD HH:MM}  ·  {count} entries
-> 2. ...
-> ...
-> N. abort — do not read any session
+Pick a session to import:
+
+| #  | Date             | Entries | Summary |
+|----|------------------|---------|---------|
+| 1  | YYYY-MM-DD HH:MM | N       | {summary} |
+| 2  | YYYY-MM-DD HH:MM | N       | {summary} |
+| …  |                  |         |           |
+| N  | —                | —       | abort — do not read any session |
 ```
 
 Format the timestamp as `YYYY-MM-DD HH:MM` (drop seconds and
-timezone — the listing is for orientation, not forensics). Do
-**not** truncate or rewrite `summary` — the helper already shapes
-it. Always include an explicit abort option as the last numbered
-choice. Track option-number → `id` internally so step 5 can call
-`scripts/chat_history.py read --session <id>` with the right id.
+timezone — the listing is for orientation, not forensics). Lead the
+`Summary` cell with the helper's `summary` field — that is the
+rough arc the user picks by (`<first user msg> → <last user msg>`
+for normal sessions, or `(N entries — no user prompts; t-mix: …)`
+for tool-only sessions). Do **not** truncate or rewrite `summary` —
+markdown table wrap handles long values. Always include an explicit
+`abort` row as the last numbered option. Track option-number → `id`
+internally so step 5 can call `scripts/chat_history.py read
+--session <id>` with the right id.
 
 ### 4. Wait for the pick
 
@@ -106,51 +107,46 @@ default. Wait for the user's response.
 
 If the user picks the abort option, stop without reading.
 
-### 5. Read the picked session verbatim
+### 5. Read the picked session silently
 
-Run `scripts/chat_history.py read --session <id>` with the picked
-`id`. The helper returns the entries as JSON.
+Run `scripts/chat_history.py read --session <id> --last <count>`,
+where `<count>` is the picked row's `count` from step 2. The
+`--last` flag is **required** — the helper defaults to 5 entries,
+which would silently truncate any longer session. The helper returns
+the entries as JSON.
 
-Render them **verbatim** in the chat — do not summarise, do not
-re-format, do not drop fields. One entry per line is acceptable;
-preserve `t`, `text`, `name`, `ts`, and any other fields the helper
-emits. Use a fenced block so timestamps and JSON survive markdown
-rendering:
+**Do not render the entries.** The verbose dump was reversed by the
+user — token cost and scroll fatigue outweighed the verbatim
+contract. Read the JSON in-context, then proceed to step 6.
 
-````
-> 📒 Session {id} — {count} entries
+### 6. Summarise and offer to resume
 
-```json
-{...entry 1...}
-{...entry 2...}
-...
-```
-````
-
-If the session is large (>50 entries), still render verbatim — but
-prepend a one-line note that the listing is long, so the user can
-scroll. Do not silently truncate.
-
-### 6. Hand back
+Emit a **2–5 sentence** summary of the picked session: the topic,
+what was decided or built, and where it left off (the last task in
+progress, if any). Plain prose — no bullets, no headings, no
+verbatim quotes.
 
-After rendering, **do not** auto-act on the content. Hand back to
-the user with a short prompt:
+Then offer the resume choice as numbered options
+(per `user-interaction`), one question per turn:
 
 ```
-> Picked session is rendered above. What would you like to extract?
+1. resume — pick up the last task from that session
+2. stop — keep the summary in context, do nothing else
 ```
 
-Any follow-up (extract decisions, copy specific entries into the
-current session, etc.) is user-directed in subsequent turns. The
-agent does not write to the current session's log on the user's
-behalf without an explicit instruction.
+Wait for the pick. Do **not** auto-resume. If the user picks
+`resume`, hand off to the relevant skill or command for that work;
+do not silently start editing files. The agent does not write to
+the current session's log on the user's behalf without an explicit
+instruction.
 
 ## Gotchas
 
-- **Verbatim, not structured.** Council Round 2 (R2-2) resolved an
-  earlier contradiction in favour of verbatim. Do not "helpfully"
-  pre-summarise — the user reads the source, then directs the
-  extraction.
+- **Summary, not verbatim.** Earlier Council R2-2 favoured verbatim
+  rendering; reversed in practice — too slow, too token-expensive.
+  The agent reads the picked session in-context and emits a 2–5
+  sentence summary. Verbatim rendering is no longer part of the
+  contract.
 - **One pick per invocation.** Multi-pick is v2. If the user wants
   a second session, run `/chat-history import` again.
 - **Read-only.** This command never writes to `agents/.agent-chat-history`

package/.agent-src/commands/compress.md

@@ -50,6 +50,18 @@ For each changed `.md` file:
      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 unambiguous: `DB`, `auth`,
+     `config`, `req`, `res`, `fn`, `impl`, `env`, `deps`, `ctx`. Skip on
+     first occurrence of the concept in the file, or when the
+     abbreviation collides with a domain term (`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; surrounding prose only. (Example phrases
+     backticked on purpose — inline-code protection skips them; never
+     strip the 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

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

@@ -76,9 +76,9 @@ Based on the type, analyze the relevant code area:
 - Identify all models and tables involved
 
 **Service context:**
-- Read the service class and its dependencies
+- Read the service class and its deps
 - Trace call chain (who calls it, what it calls)
-- Identify configuration and env dependencies
+- Identify configuration and env deps
 
 **Integration context:**
 - Find API client classes, HTTP calls

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

@@ -22,7 +22,7 @@ commands with a single entry point + sub-command dispatch.
 | `/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).
+[`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
 
 ## Dispatch
 

package/.agent-src/commands/copilot-agents.md

@@ -22,7 +22,7 @@ standalone commands with a single entry point + sub-command dispatch.
 | `/copilot-agents optimize` | `commands/copilot-agents/optimize.md` | Refactor existing AGENTS.md and copilot-instructions.md for line budgets |
 
 Sub-command names match the locked contract in
-[`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+[`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
 
 ## Dispatch
 

package/.agent-src/commands/council/default.md

@@ -30,11 +30,17 @@ The user invoked `/council default` on exactly one input mode:
 Optional invocation flag: `mode:api|manual` overrides the per-member
 and global mode for this call only (see Step 2.5).
 
-Optional **rounds**: `rounds:N` (1-3) enables multi-round debate. Round
-1 sees the artefact alone. Round 2+ sees the artefact plus anonymised
-critiques from the previous round (provider/model identity stripped).
-Total spend = N × single-round cost; surface this in the cost gate.
-Default `rounds:1`.
+Optional **rounds**: `rounds:N` (1-3) overrides the multi-round debate
+count. Round 1 sees the artefact alone. Round 2+ sees the artefact plus
+anonymised critiques from the previous round (provider/model identity
+stripped). Total spend = N × single-round cost; surface in cost gate.
+
+Default comes from `ai_council.min_rounds` in `.agent-settings.yml`
+(default `2` so members critique each other at least once before
+convergence). **Do NOT ask "how many rounds?"** when `rounds:N` is
+unset or `N <= min_rounds` — proceed with the settings default. Ask
+only when the artefact is genuinely complex; surface as a numbered
+choice with the cost delta.
 
 Optional **mode_override**: `mode_override=pr|design|optimize` swaps
 the system-prompt addendum for one of the specialised lenses
@@ -133,6 +139,12 @@ Once the user picks `1`, invoke the same arguments with `run` plus
     [--original-ask "<framing sentence>"]
 ```
 
+`--rounds` defaults to `ai_council.min_rounds` from
+`.agent-settings.yml` (or `2` if unset). Pass `--rounds N` only when
+the user explicitly asked for a different count or a complex
+artefact justifies more depth — do not pass `--rounds 1` to "save
+money" by default; settings owner already chose `min_rounds`.
+
 The CLI:
 
 - bundles the artefact via `scripts.ai_council.bundler` (redaction +

package/.agent-src/commands/council.md

@@ -26,7 +26,7 @@ sub-command swaps the mode-specific addendum.
 | `/council optimize` | `commands/council/optimize.md` | Run the council on an optimization target — ranked, evidence-based suggestions |
 
 Sub-command names match the locked contract in
-[`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+[`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
 
 ## Dispatch
 

package/.agent-src/commands/e2e-heal.md

@@ -21,7 +21,7 @@ suggestion:
 > 2. Fix a specific test file — which one?
 > 3. Fix tests that failed in CI — provide the CI run URL or error output
 
-- Read the Playwright guideline: `../../docs/guidelines/e2e/playwright.md`
+- Read the Playwright guideline: `../docs/guidelines/e2e/playwright.md`
 
 ### 2. Run failing tests
 

package/.agent-src/commands/e2e-plan.md

@@ -21,7 +21,7 @@ suggestion:
 > 2. Which feature area? (e.g., "checkout flow", "user settings", or "all visible flows")
 > 3. Is there an existing seed/setup file? (e.g., `tests/e2e/fixtures/auth.ts`)
 
-- Read the Playwright guideline: `../../docs/guidelines/e2e/playwright.md`
+- Read the Playwright guideline: `../docs/guidelines/e2e/playwright.md`
 - Check for existing test plans in `specs/` or `tests/e2e/specs/`.
 
 ### 2. Explore the application

package/.agent-src/commands/feature/dev.md

@@ -78,15 +78,15 @@ Do NOT use for single-line fixes, trivial changes, or urgent hotfixes.
 ### Phase 5: Implementation
 
 1. **Wait for explicit approval** before writing code.
-2. Create a task list with all implementation steps.
+2. Create a task list with all impl steps.
 3. Follow chosen architecture from Phase 4.
 4. Follow codebase conventions strictly (read guidelines).
 5. Update task list as progress is made.
-6. Write tests alongside the implementation.
+6. Write tests alongside the impl.
 
 ### Phase 6: Quality Review
 
-1. Review the implementation for:
+1. Review the impl for:
    - **Simplicity & DRY** — is the code as simple as possible?
    - **Correctness** — are there logic errors or missing edge cases?
    - **Conventions** — does it follow project patterns?

package/.agent-src/commands/feature.md

@@ -27,7 +27,7 @@ commands with a single entry point + sub-command dispatch.
 ## Workflow ordering
 
 Typical sequence: `explore` → `plan` → `roadmap` → `dev` (or per-step
-implementation). Use `refactor` whenever an existing plan needs an update.
+impl). Use `refactor` whenever an existing plan needs an update.
 
 ## Dispatch
 

package/.agent-src/commands/fix/seeder.md

@@ -63,9 +63,9 @@ where the seeder class is NOT the owner of the data file.
 
 ### Known Exceptions
 
-Currently there are **no exceptions**. All circular dependencies have been resolved.
+Currently there are **no exceptions**. All circular deps have been resolved.
 
-**Pattern for resolving circular dependencies:** Use two-phase seeding. The data file seeds
+**Pattern for resolving circular deps:** Use two-phase seeding. The data file seeds
 records with placeholder values (e.g., empty arrays). The Seeder's `run()` method then updates
 records with the real values using `getReference()`. Since `run()` is called after all seeders
 are initialized, the circular dependency is broken.

package/.agent-src/commands/fix.md

@@ -27,7 +27,7 @@ with a single entry point + sub-command dispatch.
 | `/fix pr-developers` | `commands/fix/pr-developers.md` | Fix and reply to **human** reviewer comments only |
 
 Sub-command names match the locked contract in
-[`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+[`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
 
 ## Dispatch
 

package/.agent-src/commands/jira-ticket.md

@@ -72,4 +72,4 @@ suggestion:
 
 ## See also
 
-- [`role-contracts`](../../docs/guidelines/agent-infra/role-contracts.md#developer) — Developer mode output contract (Goal / Plan / Changes / Tests / Open questions)
+- [`role-contracts`](../docs/guidelines/agent-infra/role-contracts.md#developer) — Developer mode output contract (Goal / Plan / Changes / Tests / Open questions)

package/.agent-src/commands/judge.md

@@ -23,7 +23,7 @@ commands with a single entry point + sub-command dispatch.
 | `/judge steps` | `commands/judge/steps.md` | Execute an ordered plan step by step, judge gate between steps |
 
 Sub-command names match the locked contract in
-[`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+[`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
 The standalone reviewer surface lives at [`/review`](review-changes.md).
 
 ## Dispatch
@@ -51,4 +51,4 @@ The standalone reviewer surface lives at [`/review`](review-changes.md).
 
 - [`subagent-orchestration`](../skills/subagent-orchestration/SKILL.md)
 - [`/review`](review-changes.md) — human-oriented self-review (Reviewer-mode contract)
-- [`role-contracts`](../../docs/guidelines/agent-infra/role-contracts.md#reviewer)
+- [`role-contracts`](../docs/guidelines/agent-infra/role-contracts.md#reviewer)

package/.agent-src/commands/memory.md

@@ -24,7 +24,7 @@ commands with a single entry point + sub-command dispatch.
 | `/memory propose` | `commands/memory/propose.md` | Append a provisional signal to the intake stream |
 
 Sub-command names match the locked contract in
-[`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+[`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
 
 ## Dispatch
 

package/.agent-src/commands/mode.md

@@ -11,7 +11,7 @@ suggestion:
 
 Sets `roles.active_role` in `.agent-settings.yml` and surfaces the active
 contract before any work. Six modes are defined in
-[`role-contracts`](../../docs/guidelines/agent-infra/role-contracts.md):
+[`role-contracts`](../docs/guidelines/agent-infra/role-contracts.md):
 
 - `developer` · `reviewer` · `tester` · `po` · `incident` · `planner`
 
@@ -37,7 +37,7 @@ Anything else: refuse. List the valid values and stop.
 
 ### 2. Validate the mode name
 
-Read [`role-contracts.md`](../../docs/guidelines/agent-infra/role-contracts.md).
+Read [`role-contracts.md`](../docs/guidelines/agent-infra/role-contracts.md).
 Extract H3 headings under `## Contract skeletons` and lowercase them.
 If `<name>` is not in that set, refuse and print the valid list.
 
@@ -62,7 +62,7 @@ exactly what the contract demands.
 ### 5. Write the active role
 
 Update `roles.active_role` in `.agent-settings.yml` using the
-[section-aware merge rules](../../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)
+[section-aware merge rules](../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)
 (preserve comments, preserve key order, touch only the changed field).
 
 For `/mode none`: set `active_role: ""`.
@@ -118,7 +118,7 @@ For `/mode` (status only):
 
 ## See also
 
-- [`role-contracts`](../../docs/guidelines/agent-infra/role-contracts.md) — the six modes
+- [`role-contracts`](../docs/guidelines/agent-infra/role-contracts.md) — the six modes
 - [`role-mode-adherence`](../rules/role-mode-adherence.md) — closing-output gate
-- [`layered-settings`](../../docs/guidelines/agent-infra/layered-settings.md) — merge rules for settings edits
+- [`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md) — merge rules for settings edits
 - [`ask-when-uncertain`](../rules/ask-when-uncertain.md) — never invent modes

package/.agent-src/commands/module.md

@@ -22,7 +22,7 @@ commands with a single entry point + sub-command dispatch.
 | `/module explore` | `commands/module/explore.md` | Load a module's structure, docs, and context into the conversation |
 
 Sub-command names match the locked contract in
-[`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+[`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
 
 ## Dispatch
 

package/.agent-src/commands/onboard.md

@@ -25,7 +25,7 @@ Triggered by the [`onboarding-gate`](../rules/onboarding-gate.md) rule when
 - Change cost profile only → [`/set-cost-profile`](set-cost-profile.md).
 - Single-value edit → ask the agent to change it, or edit
   `.agent-settings.yml` directly. The agent follows the merge rules in
-  [`layered-settings`](../../docs/guidelines/agent-infra/layered-settings.md).
+  [`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md).
 
 ## Preconditions
 
@@ -134,7 +134,7 @@ template — `minimal` + `skill_improvement: true`):
 
 Write `onboarding.onboarded: true` to `.agent-settings.yml` using the
 section-aware merge rules from
-[`layered-settings`](../../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)
+[`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)
 (preserve comments, key order, touch only the changed fields).
 
 ### 8. Summary
@@ -174,7 +174,7 @@ and stays off unless explicitly enabled.
 
   The log is local-only JSONL — nothing uploaded, nothing shared across
   projects. Reports: ./agent-config telemetry:report
-  Contract + privacy floor: docs/contracts/artifact-engagement-flow.md
+  Contract + privacy floor: .augment/contexts/contracts/artifact-engagement-flow.md
 ```
 
 Skip this block in cloud surfaces (no settings file, no log path).
@@ -200,5 +200,5 @@ local-agent concern; the cloud agent should proceed without invoking it.
 
 - [`onboarding-gate`](../rules/onboarding-gate.md) — rule that triggers this command
 - [`set-cost-profile`](set-cost-profile.md) — isolated profile change
-- [`layered-settings`](../../docs/guidelines/agent-infra/layered-settings.md) — merge rules for mid-life edits
+- [`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md) — merge rules for mid-life edits
 - [`agent-settings` template](../templates/agent-settings.md) — settings reference

package/.agent-src/commands/optimize/augmentignore.md

@@ -261,7 +261,7 @@ echo "Rules ignored: $rules_count"
 - **Lock files are always ignored** — they're huge and provide zero code insight.
 - **IDE helpers are always ignored** — generated, 20k+ lines, stale quickly.
 - **When in doubt, ignore files** — false positive is easy to fix, false negative wastes tokens silently.
-- **When in doubt, keep skills** — ignoring a needed skill causes bad output, keeping an unneeded one just wastes ~3 lines.
+- **When in doubt, keep skills** — ignoring a needed skill → bad output, keeping an unneeded one just wastes ~3 lines.
 - **Never ignore always-active rules** — only auto-loaded rules (those with `description` frontmatter) may be ignored.
 - **Never ignore meta/agent-system skills** — `agent-docs-writing-writing`, `commands`, `context-create`, `override-management`, `guidelines`, `project-docs`, `roadmap-management`, `naming`, `skill-reviewer`, `file-editor`, `copilot-config`, `copilot-agents-optimization`.
 - **Restore previously ignored skills** when the stack changes (e.g., Vue added to project → restore `vue` skill).

package/.agent-src/commands/optimize-prompt.md

@@ -0,0 +1,61 @@
+---
+name: optimize-prompt
+cluster: optimize
+description: "Optimize a raw prompt for ChatGPT, Claude, Gemini, or another AI via the 4-D methodology — BASIC vs DETAIL auto-detect, one clarifying question per turn, returns the polished prompt."
+disable-model-invocation: true
+skills: [prompt-optimizer]
+suggestion:
+  eligible: true
+  trigger_description: "optimize this prompt, make it better for ChatGPT, rewrite for Claude, sharpen this AI prompt"
+  trigger_context: "user pastes a rough prompt or names a target AI and asks for it to be improved"
+---
+
+# /optimize-prompt
+
+Entry point for the [`prompt-optimizer`](../skills/prompt-optimizer/SKILL.md) skill (persona: **Lyra**). Use when the user wants a polished prompt to paste into an external AI — not when they want the answer that prompt would produce.
+
+## Welcome
+
+On the first turn (or whenever the user invokes `/optimize-prompt` with no prompt body), respond with:
+
+```
+Hi! I'm Lyra, your AI prompt optimizer.
+
+Tell me:
+1. Your target AI — ChatGPT · Claude · Gemini · Perplexity · Other
+2. Your prompt style — DETAIL (I'll ask one question at a time first) or BASIC (I'll apply smart defaults and return the optimized prompt immediately)
+
+Examples
+- "DETAIL using ChatGPT — write me a marketing email"
+- "BASIC using Claude — help with my resume"
+
+Or just paste your rough prompt — I'll auto-detect the mode and announce it.
+```
+
+Render the welcome **once** per session. If the user invokes `/optimize-prompt <prompt>` directly, skip the welcome and run the skill.
+
+## Instructions
+
+### 1. Parse input
+
+Three input shapes:
+
+1. `/optimize-prompt` (no body) → render welcome, wait.
+2. `/optimize-prompt <prompt>` → load the skill, run mode auto-detect, proceed.
+3. `/optimize-prompt DETAIL|BASIC [using <AI>] — <prompt>` → load the skill, honor the explicit mode + target AI, proceed.
+
+### 2. Delegate to the skill
+
+Load [`prompt-optimizer`](../skills/prompt-optimizer/SKILL.md) and follow its `## Procedure` verbatim. The skill owns mode detection, the 4-D methodology, the output format, and gotchas.
+
+### 3. Hand back
+
+After the optimized prompt is delivered, end the turn. Do **not** propose to also execute the optimized prompt. Do **not** offer to commit, push, or save the result to a file — this is conversational output the user copies elsewhere.
+
+## Rules
+
+- **One question per turn** — DETAIL mode iterates; never batch clarifications (`ask-when-uncertain`).
+- **No auto-execution** — produce the prompt, not the answer it would generate, unless the user explicitly asks for both.
+- **No file writes** — the skill is conversational; no commits, no roadmap edits, no `agents/` writes.
+- **Welcome once** — don't re-render the welcome on every turn within the same session.
+- **Mirror the user's language** — the optimized prompt body uses the language the user wrote in; the skill's own scaffolding (mode announcement, "what changed" labels) stays English when the user is in English, German when they're in German (`language-and-tone` Iron Law).

package/.agent-src/commands/optimize.md

@@ -24,7 +24,7 @@ commands with a single entry point + sub-command dispatch.
 | `/optimize rtk` | `commands/optimize/rtk.md` | Create or refine project-local rtk filters |
 
 Sub-command names match the locked contract in
-[`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+[`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
 
 ## Dispatch
 

package/.agent-src/commands/override.md

@@ -22,7 +22,7 @@ commands with a single entry point + sub-command dispatch.
 | `/override manage` | `commands/override/manage.md` | Review, update, and refactor existing overrides |
 
 Sub-command names match the locked contract in
-[`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+[`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
 
 ## Dispatch
 

package/.agent-src/commands/review-changes.md

@@ -175,7 +175,7 @@ or the equivalent configured command).
 - [`/do-and-judge`](do-and-judge.md) — implementer + judge loop for a single change
 - [`/judge`](judge.md) — standalone judge, no review-changes dispatch
 - [`code-review`](../skills/code-review/SKILL.md) — human-oriented review patterns (tone, feedback handling)
-- [`role-contracts`](../../docs/guidelines/agent-infra/role-contracts.md#reviewer) — Reviewer mode output contract (Summary / Risks / Findings / Required actions / Verdict)
+- [`role-contracts`](../docs/guidelines/agent-infra/role-contracts.md#reviewer) — Reviewer mode output contract (Summary / Risks / Findings / Required actions / Verdict)
 
 ## References
 

package/.agent-src/commands/review-routing.md

@@ -107,7 +107,7 @@ After the block, ask:
 - [`reviewer-awareness`](../rules/reviewer-awareness.md) — role vocabulary
 - [`review-routing-awareness`](../rules/review-routing-awareness.md) —
   data-source rules
-- [`review-routing-data-format`](../../docs/guidelines/agent-infra/review-routing-data-format.md)
+- [`review-routing-data-format`](../docs/guidelines/agent-infra/review-routing-data-format.md)
   — YAML schemas
 - [`create-pr-description`](../skills/create-pr-description/SKILL.md) —
   consumes the routing block

package/.agent-src/commands/roadmap.md

@@ -22,7 +22,7 @@ commands with a single entry point + sub-command dispatch.
 | `/roadmap execute` | `commands/roadmap/execute.md` | Read and interactively execute a roadmap |
 
 Sub-command names match the locked contract in
-[`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+[`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
 
 ## Dispatch