From 45d779e7b8d6dcb4ddee33b88b519a45d8328e41 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EC=9D=B4=EC=88=9C=EB=AA=85?= <75053960+jsleemaster@users.noreply.github.com> Date: Thu, 2 Jul 2026 15:55:38 +0900 Subject: [PATCH 1/6] docs: sharpen shipcheck evidence review --- commands/shipcheck.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/commands/shipcheck.md b/commands/shipcheck.md index 63e6b26..cce14bf 100644 --- a/commands/shipcheck.md +++ b/commands/shipcheck.md @@ -28,7 +28,9 @@ Respond in the user's language by default. Keep code, commands, file paths, API ## Shipcheck Scope: +Intent checked: Evidence checked: +Gaps or unverified risk: ### Findings @@ -42,12 +44,23 @@ Evidence checked: ### Reproduce or bound bugs ### Defer optional scope ### Safety floor +### Intent vs implementation + +- Intended behavior: +- Implementation evidence: +- Gap: + ### Verification + +- Existing verification: +- Proposed verification: +- Unverified risk: + ### Verdict ``` ## Example Invocation ```text -/shipcheck Review this branch diff before I ship it. Return numbered findings first, then cover unnecessary code, speculative architecture, debugging gaps, optional scope, safety, and verification. +/shipcheck Review this branch diff before I ship it. Return numbered findings first, then cover unnecessary code, speculative architecture, debugging gaps, optional scope, safety, intent vs implementation, and verification. ``` From 69b039c7187b0746a750ea9adbd922cc859a5bb1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EC=9D=B4=EC=88=9C=EB=AA=85?= <75053960+jsleemaster@users.noreply.github.com> Date: Thu, 2 Jul 2026 15:56:02 +0900 Subject: [PATCH 2/6] docs: align router shipcheck rules --- skills/gooblin/SKILL.md | 1 + 1 file changed, 1 insertion(+) diff --git a/skills/gooblin/SKILL.md b/skills/gooblin/SKILL.md index 3a75aec..3b8a9a5 100644 --- a/skills/gooblin/SKILL.md +++ b/skills/gooblin/SKILL.md @@ -120,3 +120,4 @@ Before calling work done, check: - Did it avoid inventing facts? For working tree, branch, or release reviews, return numbered findings first. Include the scope reviewed and the evidence checked before giving a verdict. +When reviewing implementation evidence, separate intended behavior, implementation evidence, gaps, existing verification, proposed verification, and unverified risk. Do not treat proposed tests or unverified claims as completed proof. From b06719155fe1ea91f9a578ea5d05fdb3c89c911c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EC=9D=B4=EC=88=9C=EB=AA=85?= <75053960+jsleemaster@users.noreply.github.com> Date: Thu, 2 Jul 2026 15:56:23 +0900 Subject: [PATCH 3/6] test: validate command docs and shipcheck evidence fields --- scripts/validate-skill-pack.mjs | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/scripts/validate-skill-pack.mjs b/scripts/validate-skill-pack.mjs index f1c5a84..ab5e96d 100644 --- a/scripts/validate-skill-pack.mjs +++ b/scripts/validate-skill-pack.mjs @@ -30,6 +30,9 @@ for (const command of ['gooblin', 'clip', 'ground', 'duck', 'yak', 'shipcheck']) const file = `commands/${command}.md`; assert(fs.existsSync(file), `${file} must exist`); const text = fs.readFileSync(file, 'utf8'); + const frontmatter = text.match(/^---\n([\s\S]*?)\n---\n/); + assert(frontmatter, `${file} must have YAML frontmatter`); + assert(frontmatter[1].split('\n').some((line) => line.startsWith('description: ')), `${file} frontmatter must include description`); assert(text.includes(`# /${command}`), `${file} must document /${command}`); } @@ -43,7 +46,16 @@ for (const phrase of [ } const shipcheck = fs.readFileSync('commands/shipcheck.md', 'utf8'); -for (const phrase of ['Working tree review', 'Branch review', 'Release review', 'numbered findings']) { +for (const phrase of [ + 'Working tree review', + 'Branch review', + 'Release review', + 'numbered findings', + 'Intent checked', + 'Intent vs implementation', + 'Implementation evidence', + 'Unverified risk', +]) { assert(shipcheck.includes(phrase), `commands/shipcheck.md missing: ${phrase}`); } From b04fd9a39ce632c72a407f62d3293170f7134718 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EC=9D=B4=EC=88=9C=EB=AA=85?= <75053960+jsleemaster@users.noreply.github.com> Date: Thu, 2 Jul 2026 15:56:44 +0900 Subject: [PATCH 4/6] docs: document lightweight maintenance gates --- docs/maintenance.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/maintenance.md b/docs/maintenance.md index c25efe2..b5fe6d4 100644 --- a/docs/maintenance.md +++ b/docs/maintenance.md @@ -6,6 +6,8 @@ This is a checklist, not a process framework. Keep it small and update it when a ## Change Impact Matrix +Use this matrix as the copy-sync map. When a public behavior changes, update the smallest set of affected surfaces rather than adding a new process or parallel source of truth. + | Change | Check these surfaces | | --- | --- | | Skill behavior or skill wording | `skills/`, `commands/`, `README.md`, `examples/`, `evals/rubric.md`, `evals/fixtures/` | @@ -31,9 +33,11 @@ npm pack --dry-run For release PRs, also verify at least the current local plugin install paths documented in `docs/verified-install-paths.md`. +The validation workflow should stay tiny: checkout, Node, `npm run validate`. Do not add dependency installs, generated reports, or release automation unless a real failing PR shows the need. + ## What Not To Add -- No CI just to mirror local validation until it has clear value. +- No heavy CI beyond the lightweight validation gate. - No generated docs index unless manual drift becomes common. - No benchmark numbers without method, task set, sample size, limitations, and reproduction instructions. - No official host support claims unless the specific installer path has been verified against the released repository. From 9fe7ebe27328683b8ce103ba6e40e75acc00f76b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EC=9D=B4=EC=88=9C=EB=AA=85?= <75053960+jsleemaster@users.noreply.github.com> Date: Thu, 2 Jul 2026 15:56:56 +0900 Subject: [PATCH 5/6] docs: add contributor guidelines --- CONTRIBUTING.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..0744c2c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,34 @@ +# Contributing To Gooblin + +Gooblin is a small plugin-style Agent Skills pack. Keep changes boring, reviewable, and easy to delete. + +## What To Open + +- Bugs, typo fixes, and small documentation corrections can go straight to a pull request. +- New skills, new commands, new adapters, new hooks, benchmark claims, and distribution changes should start with an issue. +- Keep one conceptual change per pull request. + +## Design Rules + +- `/gooblin` stays the primary interface. +- Character commands are advanced shortcuts, not the main user experience. +- Skills should stay readable as plain Markdown. +- Hooks should stay tiny, dependency-free, and safe by default. +- Do not add app scaffolding, runtime services, build tooling, or dependencies without a concrete compatibility reason. + +## Before Opening A Pull Request + +Check `docs/maintenance.md` for affected surfaces, then run: + +```bash +npm run validate +git diff --check +``` + +For release or package changes, also run: + +```bash +npm pack --dry-run +``` + +Do not claim adoption, benchmarks, marketplace approval, official host support, or integrations unless the repository includes evidence and reproduction notes. From e80746f8376f9c292ac1212167ae8c739d401832 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EC=9D=B4=EC=88=9C=EB=AA=85?= <75053960+jsleemaster@users.noreply.github.com> Date: Thu, 2 Jul 2026 15:57:03 +0900 Subject: [PATCH 6/6] ci: run lightweight validation --- .github/workflows/validate.yml | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 .github/workflows/validate.yml diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml new file mode 100644 index 0000000..c412e63 --- /dev/null +++ b/.github/workflows/validate.yml @@ -0,0 +1,25 @@ +name: Validate + +on: + pull_request: + push: + branches: + - main + +permissions: + contents: read + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - name: Check out repository + uses: actions/checkout@v4 + + - name: Set up Node + uses: actions/setup-node@v4 + with: + node-version: 20 + + - name: Run validation + run: npm run validate