diff --git a/CHANGELOG.md b/CHANGELOG.md index 46f4ef1..dee3877 100644 --- a/CHANGELOG.md +++ b/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. diff --git a/README.md b/README.md index 573e214..f951b3d 100644 --- a/README.md +++ b/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. diff --git a/references/progressive-disclosure.md b/references/progressive-disclosure.md new file mode 100644 index 0000000..e1b3593 --- /dev/null +++ b/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. diff --git a/skills/basd-coding-dispatch/SKILL.md b/skills/basd-coding-dispatch/SKILL.md index 4dcb190..2a2fc13 100644 --- a/skills/basd-coding-dispatch/SKILL.md +++ b/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. diff --git a/skills/basd-coding-dispatch/references/README.md b/skills/basd-coding-dispatch/references/README.md index 4caaf4e..38fba77 100644 --- a/skills/basd-coding-dispatch/references/README.md +++ b/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. diff --git a/skills/basd-coding-dispatch/references/progressive-disclosure.md b/skills/basd-coding-dispatch/references/progressive-disclosure.md new file mode 100644 index 0000000..e1b3593 --- /dev/null +++ b/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.