docs: add progressive disclosure guidance

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## Unreleased
+
+- Added progressive-disclosure guidance for keeping `SKILL.md` lean while moving private/project-specific detail into references or project-local docs.
+- Included `references/progressive-disclosure.md` in both repo-level and skill-local reference trees.
+
 ## 0.1.0
 
 - Initial public repo skeleton.

README.md

@@ -130,6 +130,7 @@ Hermes is the flagship install path for v0.1. OpenClaw support is based on the v
 - Verify with concrete commands, transcripts, examples, or screenshots before reporting done.
 - Present explicit branch closeout options and respect no-push/no-publish/no-PR branch policy unless approval is granted.
 - Keep public repo files free of private paths, credentials, private client data, and unvalidated provider metadata.
+- Keep `SKILL.md` lean. Put private/project-specific lessons, long templates, and one-off operational history into references or project-local docs; see `references/progressive-disclosure.md`.
 - A2 run manifest / gate ledger is intentionally not introduced as a v0.1 requirement.
 
 See `skills/basd-coding-dispatch/references/quality-gates.md` for the installed skill reference and `references/quality-gates.md` for repo browsing. Use `references/quality-profiles.md`, `references/edge-case-packs.md`, `references/review-packets.md`, `references/superpowers-integration.md`, `references/plan-linter.md`, and `references/prompt-templates.md` for the detailed quality workflow.

references/progressive-disclosure.md

@@ -0,0 +1,98 @@
+# Progressive Disclosure
+
+Use this reference when adapting `basd-coding-dispatch` to a private operator setup, a larger skill library, or a public package.
+
+## Goal
+
+Keep `SKILL.md` as a router and gatekeeper, not a history log. The body should load fast, make the agent choose the right workflow, and point to detailed references only when needed.
+
+## Layering model
+
+1. **Skill description**
+   - Trigger text only.
+   - Include what the skill does, when to use it, and what it is not for.
+   - Do not put procedure detail here.
+2. **SKILL.md**
+   - Core loop.
+   - Hard gates.
+   - Request classifier.
+   - Reference routing.
+   - Pitfalls that must be active every time.
+3. **references/**
+   - Provider commands.
+   - Quality profiles.
+   - Review packet shapes.
+   - Edge-case checklists.
+   - Private or project-specific lessons.
+4. **Project-local docs**
+   - One-project launch constraints, repo paths, credentials paths, and historical state.
+   - Use project docs instead of bloating the global skill when the lesson is not reusable.
+
+## What belongs in SKILL.md
+
+Keep only instructions that must be present every time the skill fires:
+
+- Basd is dispatcher/verifier, not the implementer.
+- Approval gates: spec -> implementation plan -> code.
+- No protected-branch push, merge, deploy, production mutation, credential/customer-data handling, or destructive cleanup without explicit approval.
+- Provider/session classifier.
+- Superpowers/normalpowers requirement for broad/risky work.
+- Verification before closeout.
+- Reference routing map.
+
+## What belongs in references
+
+Move detail into references when it is:
+
+- provider-specific;
+- project-specific;
+- a historical failure mode;
+- a long prompt template;
+- a long checklist;
+- a special-case PR/merge/deploy workflow;
+- useful only for one domain such as mobile, Supabase, media apps, or commerce checkout.
+
+## Private extension pattern
+
+For private/internal installs, keep a public-safe base skill and add private references locally:
+
+```text
+skills/basd-coding-dispatch/
+  SKILL.md                         # lean, reusable router
+  references/
+    README.md                      # loading order
+    quality-gates.md               # reusable
+    provider-command-recipes.md    # reusable
+    private-project-context.md     # local-only, not public package
+```
+
+If a private install accumulates too much inline text, create a snapshot reference before slimming:
+
+```text
+references/dispatch-detailed-rules-YYYY-MM-DD.md
+```
+
+Then rewrite `SKILL.md` to point to that snapshot for archaeology only.
+
+## Public package rule
+
+The public repository must not include:
+
+- private paths;
+- credentials or credential file names;
+- private chat identifiers;
+- client/customer data;
+- unvalidated provider marketplace/plugin claims;
+- one-project internal history that does not generalize.
+
+Public examples should describe portable process, not private operations.
+
+## Verification
+
+After slimming or adapting:
+
+1. Count `SKILL.md` lines/chars before and after.
+2. Confirm all referenced files exist in the installed skill directory.
+3. Run package validation and smoke tests.
+4. Pack dry-run to confirm the references are included.
+5. Inspect changed files for private paths, token-like strings, and unsupported provider claims.

skills/basd-coding-dispatch/SKILL.md

@@ -81,3 +81,4 @@ Load only the reference needed for the task:
 - `references/session-topology.md` for single-worker, split-worker, and subagent execution shapes.
 - `references/review-orchestration.md` for independent review and review intake.
 - `references/subagent-skill-bundles.md` for assigning focused subagent work.
+- `references/progressive-disclosure.md` when adapting the skill to private installs or keeping a large internal skill lean.

skills/basd-coding-dispatch/references/README.md

@@ -16,5 +16,6 @@ Suggested loading order:
 10. Load `references/review-orchestration.md` when meaningful implementation work needs independent review or review intake.
 11. Load `references/edge-case-packs.md` for short recurring-miss checklists.
 12. Load `references/provider-command-recipes.md` for Hermes/OpenClaw installs and worker command shapes.
+13. Load `references/progressive-disclosure.md` when adapting the skill to private installs, public packages, or large internal skill libraries.
 
 Tiny fixes still receive lightweight independent review. A2 run manifest / gate ledger is intentionally not part of v0.1 public requirements.

skills/basd-coding-dispatch/references/progressive-disclosure.md

@@ -0,0 +1,98 @@
+# Progressive Disclosure
+
+Use this reference when adapting `basd-coding-dispatch` to a private operator setup, a larger skill library, or a public package.
+
+## Goal
+
+Keep `SKILL.md` as a router and gatekeeper, not a history log. The body should load fast, make the agent choose the right workflow, and point to detailed references only when needed.
+
+## Layering model
+
+1. **Skill description**
+   - Trigger text only.
+   - Include what the skill does, when to use it, and what it is not for.
+   - Do not put procedure detail here.
+2. **SKILL.md**
+   - Core loop.
+   - Hard gates.
+   - Request classifier.
+   - Reference routing.
+   - Pitfalls that must be active every time.
+3. **references/**
+   - Provider commands.
+   - Quality profiles.
+   - Review packet shapes.
+   - Edge-case checklists.
+   - Private or project-specific lessons.
+4. **Project-local docs**
+   - One-project launch constraints, repo paths, credentials paths, and historical state.
+   - Use project docs instead of bloating the global skill when the lesson is not reusable.
+
+## What belongs in SKILL.md
+
+Keep only instructions that must be present every time the skill fires:
+
+- Basd is dispatcher/verifier, not the implementer.
+- Approval gates: spec -> implementation plan -> code.
+- No protected-branch push, merge, deploy, production mutation, credential/customer-data handling, or destructive cleanup without explicit approval.
+- Provider/session classifier.
+- Superpowers/normalpowers requirement for broad/risky work.
+- Verification before closeout.
+- Reference routing map.
+
+## What belongs in references
+
+Move detail into references when it is:
+
+- provider-specific;
+- project-specific;
+- a historical failure mode;
+- a long prompt template;
+- a long checklist;
+- a special-case PR/merge/deploy workflow;
+- useful only for one domain such as mobile, Supabase, media apps, or commerce checkout.
+
+## Private extension pattern
+
+For private/internal installs, keep a public-safe base skill and add private references locally:
+
+```text
+skills/basd-coding-dispatch/
+  SKILL.md                         # lean, reusable router
+  references/
+    README.md                      # loading order
+    quality-gates.md               # reusable
+    provider-command-recipes.md    # reusable
+    private-project-context.md     # local-only, not public package
+```
+
+If a private install accumulates too much inline text, create a snapshot reference before slimming:
+
+```text
+references/dispatch-detailed-rules-YYYY-MM-DD.md
+```
+
+Then rewrite `SKILL.md` to point to that snapshot for archaeology only.
+
+## Public package rule
+
+The public repository must not include:
+
+- private paths;
+- credentials or credential file names;
+- private chat identifiers;
+- client/customer data;
+- unvalidated provider marketplace/plugin claims;
+- one-project internal history that does not generalize.
+
+Public examples should describe portable process, not private operations.
+
+## Verification
+
+After slimming or adapting:
+
+1. Count `SKILL.md` lines/chars before and after.
+2. Confirm all referenced files exist in the installed skill directory.
+3. Run package validation and smoke tests.
+4. Pack dry-run to confirm the references are included.
+5. Inspect changed files for private paths, token-like strings, and unsupported provider claims.