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 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. 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. ``` 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. 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}`); } 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.