@event4u/agent-config 1.15.0 → 1.17.0

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

@@ -13,27 +13,28 @@ execution:
 ## When to use
 
 - Creating a README for a package, library, SDK, or framework extension
-- Rewriting after major changes (new API, version bump, new registry)
-- Improving a weak package README (missing install, no example, no compatibility)
-- Documenting for Packagist, npm, or internal registries
+- Rewriting a package README after major changes (new API, version bump, new registry)
+- Improving a weak package README (missing install, no example, no compatibility info)
+- Documenting a package for Packagist, npm, or internal registries
 
-Do NOT use for:
+Do NOT use when:
 
-- Full applications, CLI tools, internal team repos → use `readme-writing`
-- Minor typos, single-section updates, deep reference docs in `/docs`
+- Documenting a full application, CLI tool, or internal team repo → use `readme-writing` instead
+- Only fixing minor typos or updating a single section
+- Writing deep reference docs that belong in `/docs`
 
 ## Goal
 
-Package README that makes adoption easy. Developer knows within 30 seconds:
-what it does, whether it fits their stack, how to install, how to use.
+Package README that makes adoption easy. A developer should know within 30 seconds:
+what it does, whether it fits their stack, how to install it, and how to use it.
 
 ## Core principles
 
-- User adoption over internal architecture — consumer first, maintainer second
-- Install + first example = most important sections
-- Compatibility must be explicit — don't imply broad support without evidence
-- First example: real, minimal, verified — no pseudo-code
-- README = onboarding, /docs = reference
+- **User adoption over internal architecture** — consumer first, maintainer second
+- **Install + first example = most important sections** — everything else is secondary
+- **Compatibility must be explicit** — don't imply broad support without evidence
+- **First code example must be real, minimal, and verified** — no pseudo-code
+- **README = onboarding, /docs = reference** — keep README focused
 
 ## Procedure
 
@@ -49,16 +50,18 @@ what it does, whether it fits their stack, how to install, how to use.
 
 ### 2. Inspect package truth sources
 
+Read files that define actual package behavior:
+
 - `composer.json` / `package.json` — name, description, requirements, scripts
-- Source entrypoints — public API, main classes/functions
+- Source entrypoints — public API surface, main classes/functions
 - Config files — publishable configs, defaults
-- CI workflows — supported versions matrix
-- Tests — actual API usage patterns
+- CI workflows — what gets tested, supported versions matrix
+- Tests — reveal actual API usage patterns
 - `CHANGELOG.md` / releases — current state, breaking changes
-- Examples directory if present
+- Examples directory — if present
 
-Extract: name, purpose, install command, runtime requirements, supported
-versions, public API, setup steps, test/lint commands.
+Extract: package name, purpose, install command, runtime requirements,
+supported versions, public API, setup steps, test/lint commands.
 
 ### 3. Choose sections
 
@@ -68,14 +71,14 @@ Priority order for packages:
 2. **Why / what problem** — if not obvious from name
 3. **Requirements / compatibility** — always (versions, extensions, frameworks)
 4. **Installation** — always (exact command, post-install steps)
-5. **Minimal usage example** — always (most important)
-6. **Configuration** — if config publish, env vars, or registration needed
-7. **More examples** — if API has multiple entry points
+5. **Minimal usage example** — always (most important section)
+6. **Configuration / setup** — if config publish, env vars, or registration needed
+7. **More examples / common use cases** — if API has multiple entry points
 8. **Development / testing** — for maintainers/contributors
-9. **Contributing** — if open/team project
+9. **Contributing** — if open or team project
 10. **License** — if applicable
 
-Skip sections with no real content. Never pad.
+Skip sections that have no real content. Never pad.
 
 ### 4. Write requirements and compatibility
 
@@ -89,12 +92,12 @@ State only what is tested and supported:
 - ext-json
 ```
 
-Don't imply broad compatibility if only tested in narrow range. Include
-framework version, language version, required extensions, services.
+Do NOT imply broad compatibility if only tested in narrow range.
+Include framework version, language version, required extensions, services.
 
 ### 5. Write installation that actually works
 
-Exact install command and required follow-up:
+Document the exact install command and any required follow-up:
 
 ```bash
 composer require vendor/package
@@ -103,25 +106,25 @@ composer require vendor/package
 php artisan vendor:publish --tag=package-config
 ```
 
-Validate each step against the codebase. Include post-install steps
-(publish, register, env setup) if required.
+Validate each step against the actual codebase.
+Include post-install steps (publish, register, env setup) if required.
 
-### 6. Write minimal working example
+### 6. Write the minimal working example
 
-**Most critical section.** Rules:
+**This is the most critical section.** Rules:
 
 - Smallest possible working example — one use case, one result
 - Real API calls, not pseudo-code
 - Copy-pasteable without hidden setup
 - Show expected result or effect if helpful
-- Must match actual package API (verify against source)
+- Must match the actual package API (verify against source)
 
 Bad: abstract, large, requires unexplained setup.
 Good: 5-15 lines, directly relevant, immediately runnable.
 
 ### 7. Keep architecture out of README — use reference-split
 
-Move deep content to dedicated docs. Recommended layout:
+Move deep content to dedicated docs. Recommended layout for packages:
 
 ```
 README.md              ← entry: what, why, install, minimal usage
@@ -133,13 +136,13 @@ docs/
   migration.md         ← version upgrade guides
 ```
 
-Multi-platform install (> 5 variants): prefer single table with deep
-links over stacked inline blocks. Occasionally-needed detail (long
-platform quirks, troubleshooting): use `<details>` — never for install,
-first example, or requirements.
+For multi-platform install (> 5 variants), prefer a single table with
+deep links over stacked inline blocks. For occasionally-needed detail
+(long platform quirks, troubleshooting), use `<details>` — never for
+install, first example, or requirements.
 
-→ See `guidelines/docs/readme-size-and-splitting.md` for thresholds,
-deep-link-table pattern, collapsibles, anti-patterns (premature
+→ See `docs/guidelines/docs/readme-size-and-splitting.md` for thresholds,
+deep-link-table pattern, collapsibles, and anti-patterns (premature
 splitting, duplication between README and `/docs/`).
 
 README = enough to adopt. Docs = enough to master.
@@ -148,11 +151,11 @@ README = enough to adopt. Docs = enough to master.
 
 - [ ] Install command is correct and complete
 - [ ] Compatibility/requirements match `composer.json` / `package.json` / CI matrix
-- [ ] First example matches real API (verified against source)
+- [ ] First example matches real API (verified against source code)
 - [ ] All documented commands exist in repo
 - [ ] No invented features or capabilities
 - [ ] Consumer can get started without reading source code
-- [ ] Deep content in docs, not README (see size guideline)
+- [ ] Deep content is in docs, not README (see size guideline)
 - [ ] Multi-platform install uses a table, not stacked blocks
 - [ ] No duplication between README and `/docs/`
 - [ ] First screen shows: what, install, requirements
@@ -167,11 +170,11 @@ README = enough to adopt. Docs = enough to master.
 
 ## Gotcha
 
-- Model writes package READMEs like app READMEs (too much architecture)
-- Model invents compatibility claims or setup steps
-- First example often too large, too abstract, or uses pseudo-code
+- Model writes package READMEs like app READMEs (too much architecture, not enough install/usage)
+- Model tends to invent compatibility claims or setup steps
+- First example is often too large, too abstract, or uses pseudo-code
 - Model over-explains internals before showing how to use the package
-- Existing README may be outdated — verify against `composer.json` / source
+- Existing README may be outdated — verify against actual `composer.json` / source, not old text
 - Model forgets post-install steps (config publish, service provider, env vars)
 
 ## Do NOT
@@ -179,7 +182,7 @@ README = enough to adopt. Docs = enough to master.
 - Do NOT invent package capabilities or compatibility
 - Do NOT skip the minimal working example
 - Do NOT prioritize internal architecture over user onboarding
-- Do NOT document commands not in the repo
+- Do NOT document commands not present in the repo
 - Do NOT hide requirements or version constraints
-- Do NOT write a giant example when 10 lines would do
-- Do NOT overload README with reference material — link to /docs
+- Do NOT write a giant example when a 10-line one would do
+- Do NOT overload README with reference material — link to /docs

package/.agent-src/skills/receiving-code-review/SKILL.md

@@ -10,9 +10,10 @@ source: package
 
 ## When to use
 
-* PR has review comments (bots like Copilot, Greptile, Augment, or human
-  reviewers) and the next step is addressing them
-* Someone pasted review feedback and asks you to "fix it" or "handle it"
+* A PR has review comments (from bots like Copilot, Greptile, Augment,
+  or from human reviewers) and the next step is to address them
+* Someone pasted review feedback into the conversation and asks you
+  to "fix it" or "handle it"
 * A pair-programming partner gave verbal suggestions about code you
   just wrote
 * You are tempted to reply "you are absolutely right" before reading
@@ -21,10 +22,10 @@ source: package
 Do NOT use when:
 
 * You are writing a review yourself (different discipline)
-* User explicitly asks for blind implementation of a specific change
-  not framed as review feedback
-* Pure style/formatting the linter should decide automatically — run
-  the linter
+* The user explicitly asks for blind implementation of a specific change
+  that is not framed as review feedback
+* The feedback is pure style/formatting that a linter should decide
+  automatically — just run the linter
 
 ## Goal
 
@@ -40,42 +41,44 @@ NO IMPLEMENTATION UNTIL THE FEEDBACK IS UNDERSTOOD AND VERIFIED.
 ```
 
 A "fix" implemented against a misread comment is worse than no fix —
-ships the wrong behavior under the label of "addressed feedback".
+it ships the wrong behavior under the label of "addressed feedback".
 
 ## Procedure
 
 ### 1. Read the full comment set before touching code
 
 Read **every** open comment on the PR first. Comments often relate to
-each other — fixing comment #3 in isolation can conflict with #5. Group:
+each other — fixing comment #3 in isolation can conflict with comment
+#5. Group them:
 
 * **Blocking** — breaks behavior, introduces a bug, security issue
-* **Important** — logic correct but design / readability issue
+* **Important** — logic is correct but design / readability issue
 * **Minor** — naming, comment style, formatting the linter missed
-* **Wrong** — reviewer misunderstood the code, or suggestion regresses
-  another behavior
+* **Wrong** — reviewer misunderstood the code, or suggestion would
+  regress another behavior
 
 ### 2. Restate each comment in your own words
 
 For every comment, write (internally or to the user): *"The reviewer
 is asking me to X because Y."*
 
-Cannot complete that sentence confidently → the comment is unclear. Ask
-for clarification **before** implementing anything. Do not implement
-the clear ones first and ask later — they may be linked.
+If you cannot complete that sentence confidently → the comment is
+unclear. Ask for clarification **before** implementing anything. Do
+not implement the clear ones first and ask later — they may be linked.
 
 ### 3. Verify each claim against the code
 
-For each blocking/important comment:
+For each comment classified as blocking/important:
 
 * Reproduce the alleged issue locally (run the test, hit the endpoint,
   read the actual runtime value — see [`systematic-debugging`](../systematic-debugging/SKILL.md))
 * Check what the code actually does, not what the reviewer **thinks**
   it does
 * Check whether the suggested fix would break another test or caller
-* Check `git blame` / history — current code may be that way for a reason
+* Check `git blame` / history — the current code may be the way it is
+  for a reason
 * **Consult memory for prior context.** Via
-  [`memory-access`](../../guidelines/agent-infra/memory-access.md),
+  [`memory-access`](../../../docs/guidelines/agent-infra/memory-access.md),
   call `retrieve(types=["historical-patterns", "architecture-decisions"],
   keys=<files in the review>, limit=3)`. A registered historical pattern
   may confirm the reviewer's concern (accept) or an architecture
@@ -86,21 +89,21 @@ For each blocking/important comment:
 
 | Situation | Response |
 |---|---|
-| Reviewer right, fix local, no caller impact | Implement, reference the comment in the commit message |
-| Reviewer right but fix affects other callers | Note downstream effects in the reply, then implement |
-| Reviewer wrong — misreading the code | Reply with evidence (specific line / test / value), do not change code |
+| Reviewer is right, fix is local, no caller impact | Implement, reference the comment in the commit message |
+| Reviewer is right but fix affects other callers | Note the downstream effects in the reply, then implement |
+| Reviewer is wrong — based on misreading the code | Reply with evidence (specific line / test / value), do not change code |
 | Reviewer suggests a feature the codebase does not use (YAGNI) | Reply asking whether the feature is actually needed, do not build speculatively |
 | Reviewer and user / architecture disagree | Escalate to the user before implementing either path |
 
 ### 5. Reply in the right place, with the right tone
 
-* Inline PR comments → reply **in the thread** of that comment, not as
-  a top-level PR comment
+* For inline PR comments → reply **in the thread** of that comment,
+  not as a top-level PR comment
 * Quote **evidence**, not opinion — "line 47 already handles this via
   `$x->isNull()`" beats "I think that's fine"
 * No flattery. No "great catch", "absolutely right", "thanks for
-  noticing". The `language-and-tone` rule already bans this — actions
-  are the acknowledgement
+  noticing". The existing `language-and-tone` rule already bans this —
+  actions are the acknowledgement
 * If you were wrong in your earlier pushback, state it factually and
   move on. No long apology
 
@@ -108,11 +111,11 @@ For each blocking/important comment:
 
 1. Blocking issues first
 2. Important issues next
-3. Minor issues last (or bundle into a single commit)
+3. Minor issues last (or bundle them into a single commit)
 4. Wrong / YAGNI: no code change, only a reply with reasoning
 
-Run relevant tests and linters **between** each group — do not batch
-four changes and then run tests once. See
+Run the relevant tests and linters **between** each group — do not
+batch four changes and then run tests once. See
 [`verify-before-complete`](../verify-before-complete/SKILL.md).
 
 ## Output format
@@ -122,34 +125,36 @@ When reporting back to the user after handling review:
 1. **Triage table** — comment → classification → decision
 2. **Implemented changes** — bullet per change with file + commit ref
 3. **Pushed back** — bullet per rejected comment with the evidence
-4. **Outstanding** — anything awaiting clarification, with the specific
-   question
+4. **Outstanding** — anything awaiting clarification, with the
+   specific question
 
 ## Gotchas
 
 * Bot comments (Copilot, Greptile) are **not** automatically right.
-  Frequently flag false positives on patterns the codebase uses
-  deliberately. Verify like a human comment.
-* A comment reading like a question ("should this be X?") is often a
-  polite way of saying "change it to X". Ask if unclear.
+  They frequently flag false positives on patterns the codebase uses
+  deliberately. Verify like you would a human comment.
+* A comment that reads like a question ("should this be X?") is often
+  a polite way of saying "change it to X". Ask if unclear instead of
+  guessing the register.
 * Resolving a comment in the GitHub UI without an accompanying fix or
-  reply silently marks it handled — reviewers may miss the lack of
-  substance.
+  reply silently marks it handled — reviewers may not notice the lack
+  of substance.
 * Stacked PRs — a comment on the base PR may already be fixed in the
   child PR. Check both before touching code.
 * A suggestion that passes review aesthetics but fails the test suite
   is still a regression. Run tests even when "the change is trivial".
-* Flattery leaks in as "good point" or "thanks". Delete before sending.
+* Flattery leaks in as "good point" or "thanks". Delete before
+  sending. The code change itself is the acknowledgement.
 
 ## Do NOT
 
 * Do NOT reply "you are absolutely right", "great catch", or any
   flattery variant — actions acknowledge, words do not
 * Do NOT implement a suggestion before verifying it against the code
-* Do NOT fix the clear items first and ask about the unclear ones later
-  when the items are linked
-* Do NOT accept a reviewer's suggestion that conflicts with an explicit
-  architectural decision without raising it
+* Do NOT fix the clear items first and ask about the unclear ones
+  later when the items are linked
+* Do NOT accept a reviewer's suggestion that conflicts with an
+  explicit architectural decision without raising it
 * Do NOT batch multiple unrelated fixes into one commit — reviewers
   cannot re-review selectively
 * Do NOT mark a comment resolved without either a code change or a
@@ -159,15 +164,15 @@ When reporting back to the user after handling review:
 
 * Replying "Fixed!" after a commit that does not actually address the
   comment (wrong file, missed case)
-* Rewriting the comment author's suggestion into your own words without
-  checking whether the reinterpretation still matches intent
+* Rewriting the comment author's suggestion into your own words
+  without checking whether the reinterpretation still matches intent
 * Implementing the YAGNI-suggested feature "just in case" the reviewer
   comes back
 * Silent disagreement — ignoring a comment without a reply
 
 ## When to hand over to another skill / command
 
-* Executing fixes across many comments → [`fix-pr-comments`](../../commands/fix-pr-comments.md)
+* Executing the fixes across many comments → [`fix-pr-comments`](../../commands/fix-pr-comments.md)
   (handles both bot + developer), [`fix-pr-bot-comments`](../../commands/fix-pr-bot-comments.md),
   [`fix-pr-developer-comments`](../../commands/fix-pr-developer-comments.md)
 * Running the full verification gate before pushing replies →
@@ -181,10 +186,10 @@ When reporting back to the user after handling review:
 
 Before considering review handling done:
 
-* [ ] Every open comment read, classified, decision made
-* [ ] No comment implemented without a one-sentence restatement
-* [ ] Every implemented fix verified by a test or runtime check
+* [ ] Every open comment has been read, classified, and has a decision
+* [ ] No comment was implemented without a one-sentence restatement
+* [ ] Every implemented fix has been verified by a test or runtime check
 * [ ] Every rejected comment has a reply quoting evidence
-* [ ] No comment marked resolved without code change or reply
+* [ ] No comment was marked resolved without code change or reply
 * [ ] No reply contains flattery
 * [ ] Linters and relevant tests pass after the changes

package/.agent-src/skills/refine-prompt/SKILL.md

@@ -217,4 +217,3 @@ For `low`, the question replaces the AC list:
 - [`work_engine.scoring.confidence`](../../templates/scripts/work_engine/scoring/confidence.py) — rubric + band thresholds
 - [`ask-when-uncertain`](../../rules/ask-when-uncertain.md) — one-question-per-turn Iron Law
 - [`artifact-drafting-protocol`](../../rules/artifact-drafting-protocol.md) — this skill was drafted under it
-- `agents/roadmaps/archive/road-to-prompt-driven-execution.md` — Phase 3 owns this skill (archived on completion)

package/.agent-src/skills/requesting-code-review/SKILL.md

@@ -11,17 +11,19 @@ source: package
 ## When to use
 
 * About to run `/create-pr` or `/prepare-for-review`
-* Feature or bug fix is code-complete and the next step is "get eyes on it"
-* A stacked PR is ready and the parent-branch reviewer needs to
+* A feature or bug fix is code-complete and the next step is "get
+  eyes on it"
+* A stacked PR is ready and you need the parent branch reviewer to
   context-switch smoothly
-* Asking a human for a quick sanity check on a specific commit or diff
+* Asking a human for a quick sanity check on a specific commit or
+  diff
 
 Do NOT use when:
 
 * You are *processing* review feedback — use [`receiving-code-review`](../receiving-code-review/SKILL.md)
-* Branch is not yet code-complete — the review-request gate requires
-  green tests and a clean diff
-* Change is documentation-only with no behavior impact
+* The branch is not yet code-complete — the review-request gate
+  requires green tests and a clean diff
+* The change is documentation-only and has no behavior impact
 
 ## Goal
 
@@ -36,9 +38,9 @@ process. A well-framed review request **halves** review time and
 NEVER REQUEST REVIEW FROM A BRANCH YOU HAVE NOT REVIEWED YOURSELF.
 ```
 
-Self-review is the single cheapest filter. Catches the issues a human
-reviewer would flag in round one, so the human can spend time on
-issues only they can see.
+Self-review is the single cheapest filter. It catches the issues a
+human reviewer would flag in round one, so the human reviewer can
+spend time on the issues only they can see.
 
 ## Procedure
 
@@ -46,18 +48,19 @@ issues only they can see.
 
 Before asking anyone else:
 
-* Read the full diff (`git diff <base>...<head>`), not just files you
-  remember touching
+* Read the full diff (`git diff <base>...<head>`), not just the files
+  you remember touching
 * Check for accidental debug output, dead code, leftover `dd()`,
   `console.log`, commented-out blocks
 * Check for secrets in diff — API keys, connection strings, tokens
 * Check file-system side effects — generated files, lockfile churn,
   IDE configs, `.env` changes
 * Run the linter + tests (see [`verify-before-complete`](../verify-before-complete/SKILL.md))
-* Find issues → fix them, do **not** ship and hope the reviewer flags
+* If you find issues → fix them, do **not** ship them and hope the
+  reviewer flags them
 
-Use [`review-changes`](../../commands/review-changes.md) as the
-structured walk-through.
+Use the [`review-changes`](../../commands/review-changes.md) command
+as the structured walk-through.
 
 ### 2. Establish the diff baseline
 
@@ -78,8 +81,8 @@ review 80 unrelated commits.
 
 ### 3. Write the review request context
 
-Any review request must answer four questions. Missing any → the
-reviewer will ask, and that round trip is preventable.
+Any review request must answer four questions. If any is missing, the
+reviewer will ask — and that round trip is preventable.
 
 | Question | Where it lives |
 |---|---|
@@ -96,22 +99,24 @@ for the title format.
 ### 4. Keep the PR reviewable in size
 
 * Target < 400 lines of real diff (excluding generated / lockfiles)
-* Bigger — consider splitting into a stack (refactor PR → feature PR)
-  so reviewers can handle each in one sitting
-* Flag generated files explicitly in the description so reviewers skip
-* Never mix a refactor + behavior change in one PR — reviewers cannot
-  isolate the risk
+* If bigger — consider splitting into a stack (refactor PR → feature
+  PR) so reviewers can handle each in one sitting
+* Flag generated files explicitly in the description so reviewers
+  skip them
+* Never mix a refactor + behavior change in the same PR — reviewers
+  cannot isolate the risk
 
 ### 5. Pick the right reviewer set
 
-* **Architectural impact** → code owner for the affected area
-* **Security-sensitive** → a security-reviewer role if the project has one
+* **Architectural impact** → the code owner for the affected area
+* **Security-sensitive** → a security-reviewer role if the project has
+  one
 * **Bots** → let Copilot / Greptile / Augment run automatically; do not
   gate human review on bot completion
 * **Cross-team change** → each affected team's owner
 
-Project with a `CODEOWNERS` file → GitHub handles this automatically;
-do not override without a reason.
+If the project has a `CODEOWNERS` file, GitHub handles this
+automatically — do not override without a reason.
 
 ### 6. Send and wait — do not nudge early
 
@@ -119,8 +124,8 @@ After the PR is open:
 
 * Respond to questions, not to the implicit "where is my review?"
   schedule
-* Review blocking and overdue → a single short nudge is appropriate;
-  do not re-open or force-push to bump the PR list
+* If the review is blocking and overdue → a single short nudge is
+  appropriate; do not re-open or force-push to bump the PR list
 
 When review comments arrive → switch to
 [`receiving-code-review`](../receiving-code-review/SKILL.md).
@@ -144,9 +149,9 @@ When handing the review request to the reviewer (PR body, Slack, email):
 * A 1000-line PR with "no behavior change" still needs review — the
   reviewer has no way to confirm "no behavior change" without reading
   every line
-* Auto-merge on approval bypasses re-review after later force-pushes —
-  use deliberately, not by habit
-* A PR description saying "see the code" is not a description —
+* Auto-merge on approval bypasses re-review after later force-pushes
+  — use deliberately, not by habit
+* A PR description that says "see the code" is not a description —
   reviewers need the why
 * Requesting review from someone without context (new hire, other
   team) without a longer pairing — they cannot do a deep review cold

package/.agent-src/skills/review-routing/SKILL.md

@@ -53,7 +53,7 @@ back. If neither file exists, emit the generic role-based fallback
 using [`reviewer-awareness`](../../rules/reviewer-awareness.md).
 
 **Also** pull agent-written signals via the shared abstraction (see
-[`memory-access`](../../guidelines/agent-infra/memory-access.md)):
+[`memory-access`](../../../docs/guidelines/agent-infra/memory-access.md)):
 
 ```python
 from scripts.memory_lookup import retrieve
@@ -189,7 +189,7 @@ Data source: <"ownership-map.yml + historical-bug-patterns.yml"
 
 - [`reviewer-awareness`](../../rules/reviewer-awareness.md)
 - [`review-routing-awareness`](../../rules/review-routing-awareness.md)
-- [`review-routing-data-format`](../../guidelines/agent-infra/review-routing-data-format.md)
+- [`review-routing-data-format`](../../../docs/guidelines/agent-infra/review-routing-data-format.md)
 - [`create-pr-description`](../create-pr-description/SKILL.md)
 - [`judge-test-coverage`](../judge-test-coverage/SKILL.md) — consumes
   the `required_test` entries from matched patterns.

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

@@ -85,7 +85,7 @@ no silent edits, max two rounds.
 ### 4. Enforce the size budget
 
 Normative source: [`size-enforcement`](../../rules/size-enforcement.md) +
-`guidelines/agent-infra/size-and-scope.md`.
+`docs/guidelines/agent-infra/size-and-scope.md`.
 
 | Category | Target |
 |---|---|

package/.agent-src/skills/security/SKILL.md

@@ -11,8 +11,13 @@ source: package
 Use when implementing authentication, authorization, or any security-sensitive functionality.
 
 Do NOT use when:
-- Validation logic only (use `laravel-validation` skill)
-- Full security audit (use `security-audit` skill)
+
+* Validation logic only — route to [`laravel-validation`](../laravel-validation/SKILL.md)
+* Full security audit — route to [`security-audit`](../security-audit/SKILL.md)
+* You need a pre-implementation threat model — route to
+  [`threat-modeling`](../threat-modeling/SKILL.md)
+* You need end-to-end authorization analysis — route to
+  [`authz-review`](../authz-review/SKILL.md)
 
 ## Procedure: Implement security for a feature
 

package/.agent-src/skills/security-audit/SKILL.md

@@ -24,9 +24,13 @@ Use this skill when:
 
 Do NOT use when:
 
-- Writing new auth/policy code → use `security`
-- Hunting for functional bugs → use `bug-analyzer` (proactive mode)
-- Investigating performance → use `performance-analysis`
+* Writing new auth/policy code — route to [`security`](../security/SKILL.md)
+* Hunting for functional bugs — route to [`bug-analyzer`](../bug-analyzer/SKILL.md) (proactive mode)
+* Investigating performance — route to [`performance-analysis`](../performance-analysis/SKILL.md)
+* You need a pre-implementation threat model for a new feature — route to
+  [`threat-modeling`](../threat-modeling/SKILL.md)
+* You need end-to-end authorization analysis for one route/action — route to
+  [`authz-review`](../authz-review/SKILL.md)
 
 ## Procedure: Security audit
 

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

@@ -83,7 +83,7 @@ The highest-signal content in a skill. Documents failure patterns.
 
 ### Killer 5: Monolithic Blob
 
-Skill exceeds size limits (see `guidelines/agent-infra/size-and-scope.md`).
+Skill exceeds size limits (see `docs/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

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

@@ -70,7 +70,7 @@ Do NOT create a skill or rule for:
 
 ### Size and structure hints
 
-→ See `guidelines/agent-infra/size-and-scope.md` for full limits.
+→ See `docs/guidelines/agent-infra/size-and-scope.md` for full limits.
 
 * Target: 300–900 words. Review for split above 1200 words. Strongly consider split above 1500 words.
 * If multiple workflows exist → split into multiple skills
@@ -262,7 +262,7 @@ Example:
 
 Skills may declare an `execution` frontmatter block (`type`, `handler`,
 `timeout_seconds`, `safety_mode`, `allowed_tools`). Default is `manual`
-(instructional only). See `guidelines/agent-infra/runtime-layer.md` for
+(instructional only). See `docs/guidelines/agent-infra/runtime-layer.md` for
 the full specification and `assisted` / `automated` semantics.
 
 ### When to create a `project-analysis-*` skill
@@ -285,5 +285,5 @@ utility libs, or simple state managers.
 
 * Write documentation-style, pointer-only, or too-broad skills ("Laravel skill")
 * Skip Procedure or use vague validation
-* Exceed size limits (see `guidelines/agent-infra/size-and-scope.md`)
+* Exceed size limits (see `docs/guidelines/agent-infra/size-and-scope.md`)
 * Duplicate rules

package/.agent-src/skills/subagent-orchestration/SKILL.md

@@ -187,4 +187,5 @@ the judge verdict.
 | Do-and-judge loop                    | [`/do-and-judge`](../../commands/do-and-judge.md) |
 | Stepwise plan with judge gates       | [`/do-in-steps`](../../commands/do-in-steps.md) |
 | Standalone judge on an existing diff | [`/judge`](../../commands/judge.md)  |
+| External / networked second opinion  | [`ai-council`](../ai-council/SKILL.md) |
 | Verifying completeness               | [`verify-before-complete`](../verify-before-complete/SKILL.md) |