From 7c8ef70a0abf36b42f58dc13c42c2bb190a7fa97 Mon Sep 17 00:00:00 2001 From: sergeliatko Date: Mon, 27 Jul 2026 15:05:03 +0200 Subject: [PATCH] route maintenance and feedback through issues --- .github/ISSUE_TEMPLATE/skill_run_feedback.yml | 28 +++++ .gitignore | 3 - .plans/0000-backlog.md | 82 ------------- .plans/0003-ci-action-versions.md | 58 ---------- .plans/0004-value-first-readme.md | 53 --------- .plans/0005-packaging-install-correctness.md | 98 ---------------- ...0006-repo-hardening-and-release-process.md | 109 ------------------ .plans/0007-template-feedback-folder.md | 75 ------------ .plans/0008-template-release-process.md | 100 ---------------- .plans/0009-community-and-sponsorship.md | 39 ------- ...0010-bootstrap-instruction-improvements.md | 69 ----------- .plans/0011-distill-authoring-guidance.md | 35 ------ .plans/README.md | 52 --------- .../bootstrap/build-skill-from-intake.md | 8 +- .template/bootstrap/cleanup-and-boundaries.md | 25 ++-- .template/bootstrap/repository-shape.md | 6 +- .../instructions/writing.instructions.md | 18 +++ .../.skill-template-feedback/.gitkeep | 0 .../.skill-template-feedback/README.md | 9 -- .template/generated/AGENTS.md | 60 ++++++++++ CHANGELOG.md | 1 + docs/FEEDBACK.md | 30 +++++ scripts/validate-skill.mjs | 58 ++++++++++ 23 files changed, 212 insertions(+), 804 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/skill_run_feedback.yml delete mode 100644 .plans/0000-backlog.md delete mode 100644 .plans/0003-ci-action-versions.md delete mode 100644 .plans/0004-value-first-readme.md delete mode 100644 .plans/0005-packaging-install-correctness.md delete mode 100644 .plans/0006-repo-hardening-and-release-process.md delete mode 100644 .plans/0007-template-feedback-folder.md delete mode 100644 .plans/0008-template-release-process.md delete mode 100644 .plans/0009-community-and-sponsorship.md delete mode 100644 .plans/0010-bootstrap-instruction-improvements.md delete mode 100644 .plans/0011-distill-authoring-guidance.md delete mode 100644 .plans/README.md create mode 100644 .template/generated/.github/instructions/writing.instructions.md delete mode 100644 .template/generated/.skill-template-feedback/.gitkeep delete mode 100644 .template/generated/.skill-template-feedback/README.md create mode 100644 .template/generated/AGENTS.md create mode 100644 docs/FEEDBACK.md diff --git a/.github/ISSUE_TEMPLATE/skill_run_feedback.yml b/.github/ISSUE_TEMPLATE/skill_run_feedback.yml new file mode 100644 index 0000000..6abd63d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/skill_run_feedback.yml @@ -0,0 +1,28 @@ +name: Skill run feedback +description: Share one factual observation from using the generated skill +title: "[Feedback]: " +labels: + - feedback +body: + - type: textarea + id: observation + attributes: + label: What happened? + description: One factual observation is enough. Describe what the skill did, missed, or made difficult. + placeholder: The skill... + validations: + required: true + - type: textarea + id: context + attributes: + label: Optional context + description: Add the intended outcome, impact, environment, or related link only when it is useful and safe to publish. + validations: + required: false + - type: checkboxes + id: privacy + attributes: + label: Public disclosure check + options: + - label: I reviewed this exact report and removed credentials, private identities, local paths, and restricted material. + required: true diff --git a/.gitignore b/.gitignore index 96ce483..97afce2 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,3 @@ tmp/ .template/state/ .idea/ *.log -.skill-template-feedback/* -!.skill-template-feedback/.gitkeep -!.skill-template-feedback/README.md diff --git a/.plans/0000-backlog.md b/.plans/0000-backlog.md deleted file mode 100644 index d812174..0000000 --- a/.plans/0000-backlog.md +++ /dev/null @@ -1,82 +0,0 @@ -# Backlog - -This is the index of template maintenance plans. Each plan corresponds to a GitHub issue filed against `TechSpokes/skill-base-template`. - -All five issues originate from one descendant repository, [skill-postgres-introspection](https://github.com/TechSpokes/skill-postgres-introspection), which was generated from this template on 2026-06-19 and which already implemented every fix locally across its releases v1.1.0 through v1.5.0. Those implementations are the ground truth referenced in each plan. - -## Plans - -| Plan | Issue | Title | Status | Phase | -| --- | --- | --- | --- | --- | -| [0003](0003-ci-action-versions.md) | #3 | Current CI action versions and a placeholder smoke-test tag | in-progress | 1 | -| [0005](0005-packaging-install-correctness.md) | #5 | Install locations, `.gitkeep` pruning, plugin manifests | in-progress | 1 | -| [0004](0004-value-first-readme.md) | #4 | Value-first generated README with install-from-release | in-progress | 2 | -| [0006](0006-repo-hardening-and-release-process.md) | #6 | Repository hardening, branch protection, release process | in-progress | 2 | -| [0007](0007-template-feedback-folder.md) | #7 | Scaffold `.skill-template-feedback/` in generated repos | in-progress | 3 | -| [0008](0008-template-release-process.md) | none | Update the template's own release process and ship v1.2.0 | in-progress | 4 | -| [0009](0009-community-and-sponsorship.md) | none | Mirror the descendant's community and sponsorship setup | in-progress | 5 | -| [0010](0010-bootstrap-instruction-improvements.md) | none | Goals-and-values transmission and an alignment-confirmation gate | in-progress | 5 | - -## Progress - -Phases 1 through 3 are implemented and committed on the `template-maintenance-baseline` branch. Each plan above is implemented in code or documentation, with `npm run validate` and a package smoke test passing after each phase. - -Plan 0008 is partially implemented. The branch-and-pull-request flow is documented in `docs/TEMPLATE-RELEASING.md`, and the template's own workflows are pinned to `actions/checkout@v7` with the `v0.0.0` smoke-test tag. The remaining 0008 work is outward-facing and gated on user confirmation: hardening the live `TechSpokes/skill-base-template` repository and cutting template v1.2.0. - -These remain for the release step and are not yet done: the version bump to `1.2.0` in `package.json` and `docs/VERSION.md`, the `## [v1.2.0]` changelog section, and `docs/releases/v1.2.0.md`. - -### Phase 5 - -Plans 0009 and 0010 are implemented on the `template-community-and-bootstrap` branch and ship together as template v1.3.0. Plan 0009 mirrors the descendant's community and sponsorship setup; its live repository settings were applied with user authorization. Plan 0010 strengthens goals-and-values transmission in the generated `AGENTS.md` and adds an alignment-confirmation step before skill construction. - -## Implementation roadmap - -The work lands in four phases on the `template-maintenance-baseline` branch, then ships as a single template release, v1.2.0. Each phase is a coherent commit set that keeps `npm run validate` green. - -### Phase 1: mechanical correctness - -Implement plan 0003 and plan 0005. Both are fully specified, low-risk, and independent. They edit generated-workflow staging, `docs/INSTALL.md`, `scripts/package-release.mjs`, the two plugin manifests, and optionally `scripts/validate-skill.mjs`. This phase removes the day-one Dependabot bump and the shipped `.gitkeep` for every future repository. - -### Phase 2: bootstrap guidance - -Implement plan 0004 and plan 0006. Both edit `.template/bootstrap/` guidance. Plan 0006 also edits `docs/RELEASING.md` and the governance files. Implement 0006 before 0004 only if convenient; they do not conflict. The one ordering constraint is that 0005 must precede 0004 so the README install section and `docs/INSTALL.md` agree on locations. - -### Phase 3: feedback loop - -Implement plan 0007. It adds the staged `.skill-template-feedback/` folder, the root git-ignore pattern, and the cleanup-and-maintenance notes. Sequence it after 0006, because both edit `.template/bootstrap/cleanup-and-boundaries.md` and the maintenance-mode `AGENTS.md` requirements. - -### Phase 4: template release process and ship - -Implement plan 0008. It updates the template's own release process to match the rigor issue #6 asks for in generated repositories, hardens the live template repository, and uses the process to cut template v1.2.0 carrying phases 1 through 3. - -## Dependency summary - -Plan 0005 precedes plan 0004, so install locations are consistent before the README guidance references them. - -Plan 0006 precedes plan 0007, so the cleanup guidance is restructured before the feedback note is added to it. - -Plan 0008 is last, because it releases the result of the other four. - -## Branch and release strategy - -All phases accumulate on one integration branch, `template-maintenance-baseline`, and ship as one minor release, v1.2.0. This keeps the changelog and release notes describing a single coherent baseline rather than five micro-releases. - -A maintainer who prefers smaller reviews can instead open one pull request per phase from this branch. The release in plan 0008 then waits until all phase pull requests merge. - -Outward-facing actions are gated. Live repository hardening, pushing the `v1.2.0` tag, and publishing the draft release require explicit user confirmation, because they change repository settings or publish content. - -## Layer model - -Every plan distinguishes three layers, because a fix often lands in more than one. Confirm which layer each change belongs to before editing. - -The live template files layer is files this repository ships and that a generated repository inherits through `Use this template`. Examples are `docs/INSTALL.md`, `scripts/package-release.mjs`, and `packaging/*/plugin.json`. - -The bootstrap guidance layer is `.template/bootstrap/*.md`, which instructs the agent how to shape and clean up a generated repository. - -The generated-workflow staging layer is `.template/generated/`, which holds files the bootstrap agent installs into the generated repository during cleanup. - -## Verification baseline - -Run `npm run validate` after any change in this repository. The validator enforces template mode, manifest fields, reference links, and packaging boundaries. - -Run `npm run package -- v0.0.0` after any change to packaging or release behavior, then inspect `dist/` for the produced assets. diff --git a/.plans/0003-ci-action-versions.md b/.plans/0003-ci-action-versions.md deleted file mode 100644 index 4ce2cf2..0000000 --- a/.plans/0003-ci-action-versions.md +++ /dev/null @@ -1,58 +0,0 @@ -# 0003: Current CI action versions and a placeholder smoke-test tag - -Issue: [#3](https://github.com/TechSpokes/skill-base-template/issues/3) - -Status: in-progress (implemented on `template-maintenance-baseline`) - -Layer: generated-workflow staging (`.template/generated/`). - -## Problem - -The generated CI workflow pins old action majors and runs a smoke test against a tag that reads like a real version. - -`.template/generated/.github/workflows/ci.yml` pins `actions/checkout@v4` on line 17 and `actions/setup-node@v4` on line 20. It runs `npm run package -- v0.1.0` on line 28. - -`.template/generated/.github/workflows/release-draft.yml` pins `actions/checkout@v4` on line 24 and `actions/setup-node@v4` on line 66. - -Because the template also ships `.github/dependabot.yml` with a GitHub Actions updater, every new repository receives a Dependabot pull request bumping these actions on its first day. The descendant received exactly that as its PR #1, bumping `actions/checkout` from v4 to v7. - -## Goal - -A repository generated from this template starts on current action majors and does not present a smoke-test tag that looks like a meaningful release version. - -## Research and decisions - -The current major versions were verified against the action repositories on 2026-06-19 using `gh api`. - -- `actions/checkout` latest release is `v7.0.0`, so pin `@v7`. -- `actions/setup-node` latest release is `v6.4.0`, so pin `@v6`. - -The descendant only bumped `actions/checkout` to v7 and left `actions/setup-node` at v4, because Dependabot opened one bump at a time. This template fix is more complete than the descendant: it updates both actions in both generated workflows. - -Keep `.github/dependabot.yml`. Dependabot is desirable; the goal is only to stop new repositories from starting a full major behind. - -The smoke-test invocation must run, so its tag must satisfy the version regex in `scripts/package-release.mjs`, which is `^v[0-9]+\.[0-9]+\.[0-9]+([.-][A-Za-z0-9.-]+)?$`. Use `v0.0.0` so the tag is a valid format that no human reads as a real release. The release-draft workflow already packages `${{ steps.meta.outputs.tag }}`, which needs no change. - -## Steps - -Edit `.template/generated/.github/workflows/ci.yml`. Change `actions/checkout@v4` to `actions/checkout@v7`. Change `actions/setup-node@v4` to `actions/setup-node@v6`. Change `npm run package -- v0.1.0` to `npm run package -- v0.0.0` and add a trailing comment marking it as a smoke-test placeholder rather than a release tag. - -Edit `.template/generated/.github/workflows/release-draft.yml`. Change `actions/checkout@v4` to `actions/checkout@v7`. Change `actions/setup-node@v4` to `actions/setup-node@v6`. - -## Secondary cleanup - -The template's own workflows `.github/workflows/template-ci.yml` and `.github/workflows/template-release-draft.yml` currently pin `actions/checkout@v6`. Bump them to `@v7` for consistency, or let the template's own Dependabot do it. This is not part of issue #3 and does not affect generated repositories. - -The hardcoded `v0.1.0` smoke-test tag also appears in `template-ci.yml` line 28. Align it to the same `v0.0.0` placeholder when touching that file. - -## Out of scope - -Release-documentation examples that show users how to cut a release belong to plan [0006](0006-repo-hardening-and-release-process.md), which converts them to `vX.Y.Z`. This plan changes only smoke-test invocations that actually run. - -## Verification - -Confirm both generated workflows reference `actions/checkout@v7` and `actions/setup-node@v6`. - -Run `npm run validate` to confirm template mode is intact. - -Confirm `v0.0.0` passes the package regex by running `npm run package -- v0.0.0` and observing that it produces assets without a tag-format error. diff --git a/.plans/0004-value-first-readme.md b/.plans/0004-value-first-readme.md deleted file mode 100644 index d0732d1..0000000 --- a/.plans/0004-value-first-readme.md +++ /dev/null @@ -1,53 +0,0 @@ -# 0004: Value-first generated README with install-from-release - -Issue: [#4](https://github.com/TechSpokes/skill-base-template/issues/4) - -Status: in-progress (implemented on `template-maintenance-baseline`) - -Layer: bootstrap guidance (`.template/bootstrap/*.md`), plus a link adjustment in `docs/INSTALL.md`. - -## Problem - -The bootstrap guidance steers the generated README toward maintainer-oriented content such as clone, `npm run validate`, and `npm run package`. A normal user who lands on a published skill should be able to download a release ZIP and install it without cloning or Node. - -The README is the front page of a generated skill. It should lead with value and an install path, not with build instructions. - -## Goal - -The bootstrap guidance instructs the agent to produce a generated README whose order is value proposition first, install-from-release second, usage third, and maintainer steps in a clearly separated section. - -## Scope and layer - -This issue is about what the bootstrap agent writes into the generated repository's README, not about this template's own README. The guidance lives in the bootstrap layer. - -The two candidate files are `.template/bootstrap/skill-quality-standard.md`, which sets the quality bar for the skill and its docs, and `.template/bootstrap/repository-shape.md`, which defines repository layout. Neither currently prescribes README order. - -## What the descendant did - -The descendant rewrote its README to open with what the skill gives the user in plain language. It then added an Install section that downloads the release ZIP from the Releases page and installs the standalone skill or the plugin. It then showed usage and moved internal and conceptual detail into `docs/`. The reference releases are its v1.2.0 and v1.4.0. - -## Steps - -Add a README-structure subsection to `.template/bootstrap/skill-quality-standard.md`. Prescribe the order: value proposition in plain language, install-from-release, usage, then a separated maintainer and contributor section. - -State that the install section links to the repository's Releases page and names the three release assets: the standalone skill ZIP, the Claude plugin ZIP, and the Codex plugin ZIP. - -State that maintainer and clone steps, including `npm run validate` and `npm run package`, stay in a clearly labeled section below usage, not in the opening. - -State that conceptual and internal detail moves into `docs/` with links from the README, so the front page stays value-first. - -Cross-reference `docs/INSTALL.md`, since the install instructions in the README and in `docs/INSTALL.md` must agree on locations after plan [0005](0005-packaging-install-correctness.md) lands. - -## Decisions - -The guidance prescribes order and section boundaries rather than exact README wording, because the skill domain is unknown at bootstrap time. The agent supplies the domain-specific value proposition; the template supplies the shape. - -This plan depends on plan [0005](0005-packaging-install-correctness.md) for the corrected install locations, so the README's install section and `docs/INSTALL.md` stay consistent. Sequence 0005 before 0004. - -## Verification - -Confirm `.template/bootstrap/skill-quality-standard.md` states the README order and names the three release assets. - -Confirm the guidance keeps maintainer commands in a separated section rather than the opening. - -Run `npm run validate` to confirm bootstrap files still satisfy template mode. The validator does not inspect prose order, so this check is editorial against the issue's acceptance description. diff --git a/.plans/0005-packaging-install-correctness.md b/.plans/0005-packaging-install-correctness.md deleted file mode 100644 index 7cca362..0000000 --- a/.plans/0005-packaging-install-correctness.md +++ /dev/null @@ -1,98 +0,0 @@ -# 0005: Install locations, `.gitkeep` pruning, plugin manifests - -Issue: [#5](https://github.com/TechSpokes/skill-base-template/issues/5) - -Status: in-progress (implemented on `template-maintenance-baseline`) - -Layer: live template files (`docs/`, `scripts/`, `packaging/`), with a supporting edit in bootstrap guidance. - -## Problem - -This issue bundles three packaging and install-correctness defects that every generated repository inherits. - -The install documentation names a skill location that no tool reads. The release packager ships placeholder scaffolding inside the ZIPs. The placeholder plugin manifests omit valid fields that hosts display. - -## Part 1: Wrong skill install locations - -`docs/INSTALL.md` lists three standalone locations on lines 17 through 19: `.github/skills/`, `.codex/skills/`, and `.claude/skills/`. The entry `.codex/skills/` is not where Codex looks. - -The cross-tool standard is `.agents/skills/`, which Codex scans from the working directory up to the repository root and which GitHub Copilot also reads. - -### Sources - -These were cited by the descendant and should be re-checked when implementing. - -- Codex skills at `https://developers.openai.com/codex/skills`. -- GitHub agent skills at `https://docs.github.com/en/copilot/concepts/agents/about-agent-skills`. -- Claude Code skills at `https://code.claude.com/docs/en/skills`. - -### Fix - -Lead with `.agents/skills/` as the cross-tool location. Keep `.claude/skills/` and `~/.claude/skills/` for Claude Code. Keep `.github/skills/` for GitHub Copilot. Remove `.codex/skills/`. - -The descendant's `docs/INSTALL.md` from its release v1.3.0 is a working model for the rewritten location list. It also adds a download-from-Releases lead paragraph, which overlaps with plan [0004](0004-value-first-readme.md). - -## Part 2: Packaging ships `.gitkeep` and empty folders - -`scripts/package-release.mjs` defines `copyDir` on lines 57 through 68, which copies every entry, including `src/assets/.gitkeep`. As a result the standalone ZIP contains an empty `assets/` folder holding only a `.gitkeep`. - -The current staged output confirms the defect: `dist/stage/placeholder-skill/assets/.gitkeep` exists. - -### Fix - -In `copyDir`, skip entries named `.gitkeep`, and prune any directory left empty after copying. Prune after recursion so nested empty directories are also removed. The descendant's implementation is the reference. - -```javascript -function copyDir(source, destination) { - fs.mkdirSync(destination, { recursive: true }); - for (const entry of fs.readdirSync(source, { withFileTypes: true })) { - if (entry.name === ".gitkeep") { - continue; - } - const sourcePath = path.join(source, entry.name); - const destinationPath = path.join(destination, entry.name); - if (entry.isDirectory()) { - copyDir(sourcePath, destinationPath); - } else { - fs.copyFileSync(sourcePath, destinationPath); - } - } - if (fs.readdirSync(destination).length === 0) { - fs.rmdirSync(destination); - } -} -``` - -Add a short comment above `copyDir` explaining that `.gitkeep` placeholders are dropped and empty directories are pruned so deliverables contain only real skill content. - -## Part 3: Plugin manifest completeness - -The placeholder manifests omit fields that the current plugin specs accept and that hosts display. - -`packaging/claude-plugin/.claude-plugin/plugin.json` omits `license` and a top-level `displayName`. - -`packaging/codex-plugin/.codex-plugin/plugin.json` omits `license`. It already carries `interface.displayName`, which is a separate field from the Claude top-level `displayName`. - -### Fix - -Add `"license"` to both manifests as a placeholder value such as `"MIT"`. Add a top-level `"displayName"` to the Claude manifest. - -Validate every manifest field against the current specs: Claude at `https://code.claude.com/docs/en/plugins-reference`, Codex at `https://developers.openai.com/codex/plugins/build`. Keep `author` as an object, matching the existing manifests. - -## Decisions - -The manifests are placeholders, rewritten during bootstrap from the generated skill. Adding placeholder `license` and `displayName` values keeps the manifests spec-complete from the first commit, so the bootstrap agent edits values rather than discovering missing keys. - -## Optional validator hardening - -`scripts/validate-skill.mjs` defines `validateManifests` on lines 211 through 234, which currently checks only `name`, `version`, and `description`. Extend it to require `license` in both manifests and a top-level `displayName` in the Claude manifest, so the install-correctness fix cannot silently regress. - -This validator change is optional within issue #5 but is the most durable way to satisfy the issue's request to validate manifests against the specs. - -## Verification - -For Part 1, confirm `docs/INSTALL.md` leads with `.agents/skills/` and contains no `.codex/skills/`. - -For Part 2, run `npm run package -- v0.0.0`, then unzip each asset in `dist/assets/` and confirm no `.gitkeep` and no empty `assets/` folder appears inside any ZIP. - -For Part 3, run `npm run validate` and confirm both manifests parse and carry the new fields. If the validator was hardened, confirm it fails when a field is removed. diff --git a/.plans/0006-repo-hardening-and-release-process.md b/.plans/0006-repo-hardening-and-release-process.md deleted file mode 100644 index 4a0d536..0000000 --- a/.plans/0006-repo-hardening-and-release-process.md +++ /dev/null @@ -1,109 +0,0 @@ -# 0006: Repository hardening, branch protection, and release process - -Issue: [#6](https://github.com/TechSpokes/skill-base-template/issues/6) - -Status: in-progress (template-side implemented on `template-maintenance-baseline`; live-repo hardening is outward-facing and pending) - -Layer: bootstrap guidance (`.template/bootstrap/cleanup-and-boundaries.md`), generated-skill docs (`docs/RELEASING.md`), and several governance files. - -## Problem - -A repository generated from this template and made public starts with no protection. There is no branch protection or ruleset on `main`, no secret scanning or push protection, and no Dependabot security updates. - -The generated `AGENTS.md` says never push directly to `main`, but nothing enforces it. - -The release documentation lacks a branch-and-pull-request flow and contains hardcoded version commands such as `npm run package -- v0.1.0`, which read like a fixed version rather than a placeholder. - -## Goal - -Bootstrap cleanup includes a hardening step with a recommended ruleset and security settings, expressed as runnable `gh` commands. The release process is documented in a single source with the branch-and-pull-request flow and version-neutral commands. - -## Part 1: Harden the repository - -Add a hardening step to `.template/bootstrap/cleanup-and-boundaries.md`. The step instructs the agent to confirm with the user before changing repository settings, because these are outward-facing actions, then apply the settings with `gh`. - -The required status check in a template-generated repository is named `Validate skill package`, which is the job name in the generated `ci.yml`. The CI workflow must already exist on the default branch for the check to be selectable. - -### Repository settings - -```bash -gh api repos/OWNER/REPO -X PATCH -F has_discussions=true -F allow_squash_merge=true -F allow_merge_commit=false -F allow_rebase_merge=false -``` - -### Secret scanning and push protection - -```bash -gh api repos/OWNER/REPO -X PATCH --input - <<'JSON' -{"security_and_analysis":{"secret_scanning":{"status":"enabled"},"secret_scanning_push_protection":{"status":"enabled"}}} -JSON -``` - -### Dependabot alerts and security updates - -```bash -gh api repos/OWNER/REPO/vulnerability-alerts -X PUT -gh api repos/OWNER/REPO/automated-security-fixes -X PUT -``` - -### Branch protection ruleset - -```bash -gh api repos/OWNER/REPO/rulesets -X POST --input - <<'JSON' -{ - "name": "main protection", - "target": "branch", - "enforcement": "active", - "conditions": { "ref_name": { "include": ["~DEFAULT_BRANCH"], "exclude": [] } }, - "bypass_actors": [], - "rules": [ - { "type": "pull_request", "parameters": { "required_approving_review_count": 0, "dismiss_stale_reviews_on_push": true, "require_code_owner_review": false, "require_last_push_approval": false, "required_review_thread_resolution": true, "allowed_merge_methods": ["squash"] } }, - { "type": "required_status_checks", "parameters": { "strict_required_status_checks_policy": true, "required_status_checks": [ { "context": "Validate skill package" } ] } }, - { "type": "non_fast_forward" }, - { "type": "deletion" }, - { "type": "required_linear_history" } - ] -} -JSON -``` - -### Decision on approvals - -Required approvals are zero so a solo maintainer is not blocked, because a maintainer cannot approve their own pull request. The guidance notes that a team with a second maintainer should raise this to one and require code-owner review. - -## Part 2: One clear release process - -Make `docs/RELEASING.md` the single source for how changes land and how a release is cut. The flow is branch, pull request, required check, squash-merge, then a version bump on the default branch and a `vX.Y.Z` tag that triggers the draft-release workflow. - -Note in the guidance that pushing a tag is not a push to the protected branch, so tagging a release is allowed under the ruleset. - -Point the generated `AGENTS.md` to `docs/RELEASING.md` instead of repeating the steps. The bootstrap requirement for this lives in `.template/bootstrap/cleanup-and-boundaries.md` under the maintenance `AGENTS.md` requirements. - -Reconcile `CONTRIBUTING.md` and `.github/PULL_REQUEST_TEMPLATE.md` with the single source so they describe the same flow. - -## Part 3: Version-neutral commands - -Replace hardcoded release-context versions with `vX.Y.Z` so they read as placeholders. The occurrences are listed below. - -- `docs/RELEASING.md` line 37, the local packaging example. -- `README.md` line 79, the template's own packaging example. -- `CONTRIBUTING.md` line 23, the packaging check. -- `docs/BOOTSTRAP-WORKFLOW.md` line 114, the packaging example. -- `.github/PULL_REQUEST_TEMPLATE.md` line 19, the packaging check. - -Distinguish release examples from smoke tests. A documentation example that shows a user how to cut a release uses `vX.Y.Z`. A smoke test that actually runs in CI uses the `v0.0.0` placeholder from plan [0003](0003-ci-action-versions.md). The pull-request template and contributing checks are illustrative, so they take `vX.Y.Z`. - -## Decisions - -The hardening guidance ships as instructions plus runnable commands rather than as automation, because branch protection and security settings are outward-facing and require user confirmation per the template's own values. The agent runs them only after confirming. - -The ruleset values are copied from the descendant's verified configuration, including squash-only merges, required conversation resolution, required linear history, and blocked force-push and deletion. - -## Verification - -Confirm `.template/bootstrap/cleanup-and-boundaries.md` contains the hardening step with all four command groups and the approvals decision. - -Confirm `docs/RELEASING.md` describes the branch-and-pull-request flow and the tag trigger, and that `AGENTS.md`, `CONTRIBUTING.md`, and the pull-request template point to it without duplicating steps. - -Search the repository for hardcoded package versions and confirm none remain in release-context docs outside the changelog and release notes. A representative search is `grep -rnE 'package -- v[0-9]'`, expecting only smoke-test `v0.0.0` occurrences. - -Run `npm run validate` to confirm template mode and governance files remain consistent. diff --git a/.plans/0007-template-feedback-folder.md b/.plans/0007-template-feedback-folder.md deleted file mode 100644 index 2902966..0000000 --- a/.plans/0007-template-feedback-folder.md +++ /dev/null @@ -1,75 +0,0 @@ -# 0007: Scaffold `.skill-template-feedback/` in generated repos - -Issue: [#7](https://github.com/TechSpokes/skill-base-template/issues/7) - -Status: in-progress (implemented on `template-maintenance-baseline`) - -Layer: generated-workflow staging (`.template/generated/`), bootstrap guidance, and the root `.gitignore`. - -## Problem - -There is no standard channel for a generated skill repository to capture the gaps it finds in this template and route them back upstream. While maintaining a generated skill, an agent or maintainer notices outdated defaults, missing safeguards, or unclear instructions, but that feedback has nowhere to live and tends to get lost. - -The four improvements in issues #3, #4, #5, and #6 were all found this way, by hand, in one descendant. - -## Goal - -A generated repository carries a tracked `.skill-template-feedback/` folder whose job is to capture template gaps locally and surface them upstream as issues or pull requests. The maintenance documentation mentions the practice. - -## What the descendant did - -In its release v1.5.0 the descendant added a tracked `.skill-template-feedback/` folder. The folder's `README.md` and a `.gitkeep` are tracked, so the convention travels with the repository. Everything else in the folder is git-ignored, so working notes and draft artifacts stay local and never ship in the skill package. - -The descendant also keeps a portable upgrade guide in the folder, `SKILL-REPO-UPGRADE-GUIDE.md`, which is a single skill-agnostic checklist for bringing other template-generated repositories up to the current baseline. - -### Git-ignore pattern - -```gitignore -.skill-template-feedback/* -!.skill-template-feedback/.gitkeep -!.skill-template-feedback/README.md -``` - -## Design decision: how the scaffold travels - -A `.skill-template-feedback/` folder is meaningless in the template itself, because the template has no upstream template to send feedback to. So the folder must be installed into the generated repository during bootstrap, not shipped pre-populated at the template root. - -Stage the folder under `.template/generated/.skill-template-feedback/`, mirroring how the generated workflows are staged under `.template/generated/.github/workflows/`. Bootstrap cleanup installs it into the generated repository root. - -Ship the git-ignore pattern in the template's root `.gitignore`. The pattern is inert in the template, where the folder does not exist, and it travels automatically through `Use this template`, so the generated repository ignores working notes from its first commit. - -## Steps - -Create `.template/generated/.skill-template-feedback/README.md`. Base it on the descendant's README. State that the folder is a local staging area for notes about the template the skill was generated from, name the upstream as `TechSpokes/skill-base-template`, and explain the capture-then-surface loop. State that only `README.md` and `.gitkeep` are tracked and that nothing in the folder ships in the skill package. - -Add the git-ignore pattern above to the template's root `.gitignore`. - -Add an install step to `.template/bootstrap/cleanup-and-boundaries.md`. The step instructs the agent to copy the staged `.skill-template-feedback/` into the generated repository root, create the tracked `.gitkeep`, and confirm the git-ignore pattern is present. - -Add a maintenance-practice note to the maintenance `AGENTS.md` requirements in `.template/bootstrap/cleanup-and-boundaries.md`. The note states that when maintaining a generated skill reveals a template gap, the agent captures it in `.skill-template-feedback/` and opens an issue or pull request on the template. - -Add `.plans/` to the cleanup deletion list in `.template/bootstrap/cleanup-and-boundaries.md`, so the template's own maintenance backlog does not leak into a generated repository. This closes the boundary described in [README.md](README.md). - -## Optional: ship the portable upgrade guide - -The descendant's `SKILL-REPO-UPGRADE-GUIDE.md` is a skill-agnostic checklist that lets one descendant upgrade another to the current baseline. Optionally stage a generic version under `.template/generated/.skill-template-feedback/` so every descendant inherits it. - -If shipped, the guide must stay skill-agnostic and must be regenerated from the merged set of issues #3 through #7 once those land, so it reflects the current template baseline rather than the descendant's snapshot. - -## Decisions - -The git-ignore pattern ships at the template root rather than being written during cleanup, because a pattern is inert without the folder and shipping it removes one manual cleanup step. - -The README and upgrade guide are staged under `.template/generated/` rather than shipped at the template root, because a feedback-to-upstream folder is self-referential and meaningless in the template itself. - -This plan shares two edit targets with plan [0006](0006-repo-hardening-and-release-process.md): the cleanup guidance and the maintenance `AGENTS.md` requirements. Sequence 0006 first so the feedback note is added beside an existing hardening and release section rather than into a file still being restructured. - -## Verification - -Confirm `.template/generated/.skill-template-feedback/README.md` exists and names the upstream template and the capture-then-surface loop. - -Confirm the root `.gitignore` contains the three-line pattern. - -Confirm `.template/bootstrap/cleanup-and-boundaries.md` instructs the agent to install the folder, records the maintenance practice, and lists `.plans/` for deletion. - -Run `npm run validate` and confirm template mode is intact and the staged folder does not trip packaging-boundary checks. diff --git a/.plans/0008-template-release-process.md b/.plans/0008-template-release-process.md deleted file mode 100644 index fedc0af..0000000 --- a/.plans/0008-template-release-process.md +++ /dev/null @@ -1,100 +0,0 @@ -# 0008: Update the template's own release process and ship v1.2.0 - -Issue: none. This plan organizes the release of plans 0003 through 0007 and applies issue #6's rigor to the template repository itself. - -Status: in-progress (Parts 1 and 3 done; Parts 2 and 4 are outward-facing and pending confirmation) - -Layer: template-own release machinery (`docs/TEMPLATE-RELEASING.md`, `.github/workflows/template-release-draft.yml`), template governance, and live repository settings. - -## Problem - -The template's release process already runs. Releases v1.0.0 and v1.1.0 were drafted by `.github/workflows/template-release-draft.yml`. Two gaps remain. - -The process is not documented as a branch-and-pull-request flow, the same gap that issue #6 fixes for generated repositories. `docs/TEMPLATE-RELEASING.md` lists a checklist and the tag trigger but not how a change lands on `main` first. - -The live template repository is under-hardened. Its `main` ruleset, named `Protect main`, enforces only `deletion` and `non_fast_forward`. It does not require a pull request or the CI check. Secret scanning, push protection, and Dependabot security updates are disabled. The template should meet the bar it now asks generated repositories to meet. - -## Goal - -The template's release process is documented as a branch, pull request, required check, squash-merge, then tag flow. The live template repository is hardened to the same baseline issue #6 prescribes. The five fixes ship as template v1.2.0 through that process. - -## Part 1: Document the branch-and-pull-request flow - -Update `docs/TEMPLATE-RELEASING.md` to state that changes land on `main` through a branch, a pull request, the required CI check, and a squash-merge, before a release is cut. - -State that the version bump and the `vX.Y.Z` tag come after the change is merged, and that pushing a tag is not a push to the protected branch, so it is allowed under the ruleset. - -Keep the existing asset policy unchanged. Template releases publish source archives, not the placeholder `dist/assets/*.zip`. - -## Part 2: Harden the live template repository - -These are outward-facing actions on `TechSpokes/skill-base-template` and require user confirmation before running. The required status check name is `Validate template scaffold`, the job name in `.github/workflows/template-ci.yml`. Note that this differs from the generated-repository check name `Validate skill package` used in plan [0006](0006-repo-hardening-and-release-process.md). - -### Repository settings - -```bash -gh api repos/TechSpokes/skill-base-template -X PATCH -F allow_squash_merge=true -F allow_merge_commit=false -F allow_rebase_merge=false -``` - -### Secret scanning and push protection - -```bash -gh api repos/TechSpokes/skill-base-template -X PATCH --input - <<'JSON' -{"security_and_analysis":{"secret_scanning":{"status":"enabled"},"secret_scanning_push_protection":{"status":"enabled"}}} -JSON -``` - -### Dependabot security updates - -```bash -gh api repos/TechSpokes/skill-base-template/vulnerability-alerts -X PUT -gh api repos/TechSpokes/skill-base-template/automated-security-fixes -X PUT -``` - -### Upgrade the existing ruleset - -The ruleset `Protect main` already exists, so update it rather than create a second one. Fetch its id, then add the pull-request, required-status-check, and linear-history rules to match the baseline in plan [0006](0006-repo-hardening-and-release-process.md). - -```bash -gh api repos/TechSpokes/skill-base-template/rulesets --jq '.[] | "\(.id) \(.name)"' -``` - -Required approvals stay at zero so a solo maintainer is not blocked, matching the decision in plan 0006. - -## Part 3: Align the template workflow action versions - -`.github/workflows/template-release-draft.yml` pins `actions/checkout@v6` on line 24. `.github/workflows/template-ci.yml` pins `actions/checkout@v6` on line 17. Bump both to `@v7` to match the current major confirmed in plan [0003](0003-ci-action-versions.md). The `actions/setup-node@v6` pins are already current. - -Align the `template-ci.yml` smoke-test tag on line 28 to the `v0.0.0` placeholder, consistent with plan 0003. - -## Part 4: Cut template v1.2.0 - -After phases 1 through 3 of the roadmap are merged, cut the release using the documented process. - -Bump `version` in `package.json` to `1.2.0`. Update `docs/VERSION.md` to state the current version is `1.2.0`. - -Move the changes from `[Unreleased]` in `CHANGELOG.md` into a new `## [v1.2.0]` section summarizing the five fixes. - -Add `docs/releases/v1.2.0.md` with the release notes. - -Run `npm run validate`. Run `npm run package -- v1.2.0` as a local smoke test. - -Push the `v1.2.0` tag, which triggers `template-release-draft.yml` to create a draft release. Review and publish the draft. The tag push and the publish require user confirmation. - -## Decisions - -The template repository is hardened to the same baseline it prescribes for descendants, so the template demonstrates the practice rather than only documenting it. - -The existing `Protect main` ruleset is upgraded in place rather than replaced, to avoid two overlapping rulesets on the same branch. - -The release is a single minor version, v1.2.0, carrying all five fixes, so the changelog and release notes describe one coherent baseline. - -## Verification - -Confirm `docs/TEMPLATE-RELEASING.md` describes the branch-and-pull-request flow and the tag trigger. - -Confirm `template-release-draft.yml` and `template-ci.yml` reference `actions/checkout@v7`. - -After hardening, confirm `gh api repos/TechSpokes/skill-base-template/rules/branches/main` lists pull-request, required-status-check, and linear-history rules, and that the security settings report as enabled. - -After the release, confirm the draft release for `v1.2.0` exists with notes from `docs/releases/v1.2.0.md` and that no `dist/assets/*.zip` were attached. diff --git a/.plans/0009-community-and-sponsorship.md b/.plans/0009-community-and-sponsorship.md deleted file mode 100644 index 2a7e990..0000000 --- a/.plans/0009-community-and-sponsorship.md +++ /dev/null @@ -1,39 +0,0 @@ -# 0009: Mirror the descendant's community and sponsorship setup - -Issue: none. Requested directly: match the descendant's sponsorship and community settings on the template. - -Status: in-progress (implemented on `template-community-and-bootstrap`) - -Layer: live repository settings and the `.github/FUNDING.yml` file. - -## Problem - -The template's community setup diverged from the descendant `skill-postgres-introspection`. The template had Discussions disabled, Projects and Wiki enabled, and a bare `FUNDING.yml`. The descendant had Discussions enabled, Projects and Wiki disabled, and a `FUNDING.yml` with documented platform examples. - -## Goal - -The template's sponsorship and community configuration matches the descendant, so the template demonstrates the same setup it produces. - -## What the descendant has - -The descendant's `.github/FUNDING.yml` keeps `github: TechSpokes` and adds commented examples for `open_collective`, `patreon`, `ko_fi`, and a `custom` TechSpokes URL. - -The descendant repository has Discussions enabled with the default categories, Projects disabled, and Wiki disabled. - -## Steps - -Enrich `.github/FUNDING.yml` to match the descendant: keep `github: TechSpokes` and add the commented platform examples. - -Apply the live repository settings on `TechSpokes/skill-base-template`: enable Discussions, disable Projects, disable Wiki. These were applied with `gh api repos/TechSpokes/skill-base-template -X PATCH -F has_discussions=true -F has_projects=false -F has_wiki=false`. - -## Decisions - -The repository settings are outward-facing and were applied with explicit user authorization. The `FUNDING.yml` change is a tracked file and ships in the next release. - -Projects and Wiki are disabled to match the descendant's focused setup, not only to enable Discussions. The descendant deliberately keeps both off. - -## Verification - -Confirm `gh api repos/TechSpokes/skill-base-template` reports `has_discussions` true and `has_projects` and `has_wiki` false. - -Confirm `.github/FUNDING.yml` carries the commented platform examples. diff --git a/.plans/0010-bootstrap-instruction-improvements.md b/.plans/0010-bootstrap-instruction-improvements.md deleted file mode 100644 index e7128a3..0000000 --- a/.plans/0010-bootstrap-instruction-improvements.md +++ /dev/null @@ -1,69 +0,0 @@ -# 0010: Strengthen goals-and-values transmission and add an alignment-confirmation gate - -Issue: none. Requested directly after reviewing the descendant's generated agent instructions. - -Status: in-progress (implemented on `template-community-and-bootstrap`) - -Layer: bootstrap guidance (`.template/bootstrap/*.md`) and the template `AGENTS.md`. - -## Problem - -Two weaknesses surfaced when comparing the descendant's generated `AGENTS.md` with the bootstrap guidance that should produce it. - -First, the descendant's `AGENTS.md` transmits goals and values for local decisions very well. It has a "Core principles the skill must keep" section and an explicit decision stance: surface findings as obstacles to the goal, weigh local context, and bring decisions to the user rather than acting alone or silently deferring. The bootstrap guidance supports this in its theory, but the operational checklists that the agent actually follows do not require it, so a generated `AGENTS.md` may omit it. - -Second, the exploratory phase has no alignment-confirmation step. The agent assesses intake adequacy, resolves gaps through inference and scope narrowing, and passes the build readiness gate, then builds. It never confirms its synthesized understanding with the user. When the readiness decision rested on the agent's own guesses, construction can start misaligned with the user's intent. - -## Goal - -A generated `AGENTS.md` reliably carries the skill's core principles and a decision stance that enables aligned local decisions. The bootstrap agent confirms its synthesized understanding with the user before it starts building the skill. - -## Part 1: Goals and values for local decisions - -The descendant's `AGENTS.md` is the model. Its core-principles section states each durable principle with its rationale, and its decision stance tells a future agent how to act when the exact instruction does not fit: diagnose, weigh local context, and confirm with the user. - -The theory already exists. `cross-intelligence-communication.md` states "Give future agents enough reasoning to make local decisions" and prescribes a "Writing Repository Agent Instructions" pattern with values and local judgment rules. The gap is in the operational checklists. - -Update the `Generated AGENTS.md Rules` checklist in `cross-intelligence-communication.md` to require a core-principles-and-decision-stance section. - -Update the `Maintenance AGENTS.md Requirements` in `cleanup-and-boundaries.md` to require the same, aligned with the cross-intelligence wording. - -## Part 2: Alignment confirmation before construction - -Add an alignment-confirmation step to `intake-adequacy-and-resolution.md`. After the build readiness gate passes and before writing `src/SKILL.md`, the agent presents a short synthesis the user can confirm or correct: the skill candidate and goal, the activation and non-activation boundary, the core workflow in outline, the key assumptions the decision depends on, and anything narrowed or deferred. - -Frame it to avoid the existing `Questionnaire Transfer` pitfall. The agent presents synthesized understanding, not a list of design questions. The agent does the design; the user confirms the direction. Scale the step to how much the readiness decision rested on inference rather than direct evidence. - -Add a gate in `build-skill-from-intake.md` between Phase 2 (Skill Design) and Phase 3 (Build The Skill Product), so the confirmation happens once the design synthesis exists and before construction. - -Add a must-follow rule to the template `AGENTS.md`: do not start `src/SKILL.md` until the build readiness gate passes and the agent's understanding is confirmed with the user. - -Add the confirmation to the Phase 0 completion criteria in `intake-adequacy-and-resolution.md`. - -## Decisions - -The changes target the operational checklists and the phase sequence rather than the theory, because the theory already endorses both goals: reasoning for local decisions and user alignment. The risk was that the checklists let an agent skip them. - -The alignment-confirmation step is explicitly distinguished from the resolution ladder's `Ask` rung. `Ask` resolves a specific blocking gap. Alignment confirmation validates the agent's overall interpretation so construction starts from shared understanding. - -## Part 3: Reader-standpoint language alignment - -An audit of the bootstrap control plane found the instruction files opened in author and provenance voice ("This file is a distilled operational version of TechSpokes research"), referenced private research the executing agent cannot see, and omitted recently added directories from the repository-shape and cleanup guidance. - -Reframe the opening of each bootstrap instruction file to address the executing agent and its task. Keep authorship attribution in `docs/PROVENANCE.md` and the README, not in each operational file. Remove references to private research the reader cannot access. - -Document `.plans/` and `.skill-template-feedback/` in the repository-shape trees, and add the feedback-folder install and the `.plans/` deletion to the Phase 7 cleanup steps, so the workflow and the shape guidance agree with `cleanup-and-boundaries.md`. - -Do not vendor or expose the private theory or approaches the template distills. The instruction files carry only the operational, public-appropriate form. - -## Verification - -Confirm `cross-intelligence-communication.md` and `cleanup-and-boundaries.md` require a core-principles-and-decision-stance section in the generated `AGENTS.md`. - -Confirm the bootstrap instruction files open by addressing the executing agent, and that no file references private research material. - -Confirm `intake-adequacy-and-resolution.md` has an alignment-confirmation step that is distinguished from the `Ask` rung and scaled to the reliance on inference. - -Confirm `build-skill-from-intake.md` gates Phase 3 on the confirmation, and the template `AGENTS.md` carries the must-follow rule. - -Run `npm run validate` to confirm template mode is intact. diff --git a/.plans/0011-distill-authoring-guidance.md b/.plans/0011-distill-authoring-guidance.md deleted file mode 100644 index 0f54831..0000000 --- a/.plans/0011-distill-authoring-guidance.md +++ /dev/null @@ -1,35 +0,0 @@ -# 0011: Distill authoring and reasoning guidance into the bootstrap docs - -Issue: none. Requested directly after reviewing the TechSpokes source corpus the template draws on. - -Status: in-progress (implemented on `template-community-and-bootstrap`) - -Layer: bootstrap guidance (`.template/bootstrap/*.md`). - -## Problem - -The template distills a body of TechSpokes guidance, credited in `docs/PROVENANCE.md`: the cross-intelligence communication theory, the AGENTS.md and README specifications, and a problem-solving framework. The bootstrap docs captured the core but left out several concrete, publishable rules that make the agent's output more consistent. - -## Goal - -Strengthen the bootstrap guidance with distilled, paraphrased operational rules from the source material, written in the template's own voice. Do not vendor or quote the private theory, its formulas, its translation matrix, its cited figures, or the problem-solving framework's taxonomy and schemas. - -## What was added - -`theory-context.md` gains a "How Meaning Survives Transport" section: write for one-way delivery, protect the weakest stage by stating the goal, track goal survival separately from rule survival, treat distortion as worse than loss, design for the specific boundary crossed, and repeat critical constraints on purpose. - -`cross-intelligence-communication.md` gains the AGENTS.md authoring shape: the section order, read-depth guidance in the Summary, an under-100-line size target, and the rule to write `AGENTS.md` only when a standalone Summary is useful. - -`skill-quality-standard.md` gains README required elements, anti-patterns, and sizing, plus a `Script Rules` section for commenting any scripts a generated skill ships. - -`intake-adequacy-and-resolution.md` gains an "Asking High-Value Questions" section: ask only for genuine gaps, phrase questions as confirm-or-refute tests, ask the question that separates competing interpretations, separate fixed constraints from preferences, do not promote nearby mentions to requirements, and recompute gaps after each answer. - -## Decisions - -Each addition is paraphrased and kept digestible: headed sections, flat atomic lists, short rationale. The private theory's formal apparatus and the framework's implementation details were deliberately excluded; only the generic, publishable principles were reflected. - -The script-commenting rule is self-contained rather than pointing to a specific installed skill, so it stays portable in a generated repository. - -## Verification - -Confirm the four bootstrap docs carry the additions, that no proprietary formula, matrix, figure, or taxonomy appears, and that `npm run validate` passes. diff --git a/.plans/README.md b/.plans/README.md deleted file mode 100644 index c5c4891..0000000 --- a/.plans/README.md +++ /dev/null @@ -1,52 +0,0 @@ -# Plans - -This folder is the tracked backlog for template maintenance work on `skill-base-template` itself. It is the machinery for planning changes to the template before they are implemented. - -## What belongs here - -This folder holds one Markdown plan per unit of maintenance work, usually one plan per GitHub issue. - -A plan describes the problem, the goal, the exact files to change, the ordered steps, the decisions and research behind them, the risks, and the verification method. - -Each plan is written to be executed later by an agent or maintainer who did not do the planning. A plan must therefore be self-contained. - -## What does not belong here - -User skill-source material does not belong here. It lives in `.intake/`. - -Bootstrap control instructions for building a generated skill do not belong here. They live in `.template/`. - -Implementation of the work does not belong here. Plans describe changes; they do not make them. - -## File naming - -Each plan filename starts with a four-digit number that matches its GitHub issue number, followed by a short slug. - -```text -.plans/ -|-- README.md # this file -|-- 0000-backlog.md # index of all plans, status, and priority -`-- NNNN-short-slug.md # one plan; NNNN matches the GitHub issue number -``` - -When a plan does not map to a single issue, allocate the next free number above the highest issue number. - -## Status values - -A plan's status line uses one of the following words. - -- `proposed`: drafted, not yet approved to start. -- `ready`: approved, can be implemented as written. -- `in-progress`: implementation started on a branch. -- `done`: merged, kept for history until the issue is closed. -- `dropped`: will not be done, with a one-line reason recorded. - -## Lifecycle and boundaries - -This folder is part of the template's own repository, not part of a generated skill. It travels into a new repository when someone clicks `Use this template`, where it has no meaning. - -The release packager `scripts/package-release.mjs` stages only `src/` and `packaging/`, so `.plans/` never ships in any release ZIP. - -Bootstrap cleanup should delete `.plans/` along with `.template/` when a generated repository transitions to maintenance mode. The plan in [0007-template-feedback-folder.md](0007-template-feedback-folder.md) adds that deletion to the cleanup guidance in `.template/bootstrap/cleanup-and-boundaries.md`. - -The downstream equivalent of this folder for a generated skill is `.skill-template-feedback/`, which routes template gaps back upstream to this repository. That folder is designed in [0007-template-feedback-folder.md](0007-template-feedback-folder.md). diff --git a/.template/bootstrap/build-skill-from-intake.md b/.template/bootstrap/build-skill-from-intake.md index 2000593..7d3c12a 100644 --- a/.template/bootstrap/build-skill-from-intake.md +++ b/.template/bootstrap/build-skill-from-intake.md @@ -248,17 +248,17 @@ Convert the repository to maintenance mode after the generated skill is accepted Required cleanup: -- Install `.skill-template-feedback/` in the repository root from `.template/generated/`, and confirm its git-ignore pattern is present. +- Rewrite the root `AGENTS.md` from `.template/generated/AGENTS.md`, replacing every placeholder with the generated skill's actual maintenance contract. +- Install `.template/generated/.github/instructions/writing.instructions.md` and adapt it only when the generated domain needs narrower prose rules. +- Rewrite `docs/FEEDBACK.md` and the skill-run feedback form for the generated repository, then route durable feedback through GitHub Issues. - Harden the repository as described in `.template/bootstrap/cleanup-and-boundaries.md`. - Delete `.template/`. -- Delete `.plans/`. - Rewrite `README.md` for the generated skill. -- Rewrite `AGENTS.md` for maintaining the generated skill. - Keep `.intake/README.md` if future raw update intake is useful. - Remove raw intake files when they should not remain in source control. - Ensure release packaging excludes `.template/` and `.intake/`. -Use `.template/bootstrap/cleanup-and-boundaries.md` for the full handoff, including repository hardening, the community file rewrites, and the feedback-folder details. +Use `.template/bootstrap/cleanup-and-boundaries.md` for the full handoff, including repository hardening, community file rewrites, maintenance instructions, and issue-centered feedback routing. Rationale: Cleanup converts the repository's identity. Before cleanup, the repository is a skill factory. After cleanup, it is the skill. diff --git a/.template/bootstrap/cleanup-and-boundaries.md b/.template/bootstrap/cleanup-and-boundaries.md index b6007fe..fb5f80e 100644 --- a/.template/bootstrap/cleanup-and-boundaries.md +++ b/.template/bootstrap/cleanup-and-boundaries.md @@ -20,9 +20,9 @@ Leaving bootstrap files behind gives future agents two competing frames: build a ## Cleanup Is Required -The normal path ends with deleting `.template/` and `.plans/`. Keeping `.template/` is only acceptable when the repository is intentionally still being used as a template. +The normal path ends with deleting `.template/`. Keeping `.template/` is only acceptable when the repository is intentionally still being used as a template. -Delete `.plans/` too. It is the template's own maintenance backlog and has no meaning in a generated skill repository. +Keep durable backlog, feedback, and delivery state in GitHub Issues and pull requests rather than copying template planning files into each generated repository. ## Files To Rewrite @@ -33,6 +33,7 @@ Rewrite these files before deleting `.template/`: - `docs/ARCHITECTURE.md` - `docs/TESTING.md` - `docs/THREAT-MODEL.md` +- `docs/FEEDBACK.md` - `docs/RELEASING.md` - `CONTRIBUTING.md` - `SUPPORT.md` @@ -40,6 +41,7 @@ Rewrite these files before deleting `.template/`: - `.github/CODEOWNERS` - `.github/FUNDING.yml` - `.github/copilot-instructions.md` +- `.github/instructions/writing.instructions.md` - `.github/workflows/*` - `.github/ISSUE_TEMPLATE/*.yml` - `.github/DISCUSSION_TEMPLATE/*` @@ -162,21 +164,15 @@ JSON Required approvals are zero so a solo maintainer is not blocked, because a maintainer cannot approve their own pull request. Raise this to one and require code-owner review when a second maintainer is active. -## Scaffold The Feedback Folder +## Route Feedback Through GitHub Issues -Install a `.skill-template-feedback/` folder in the generated repository root. It is the local channel for routing template gaps back upstream to this template. +Use GitHub Issues as the generated repository's only durable feedback and maintenance queue. Rewrite `docs/FEEDBACK.md` and `.github/ISSUE_TEMPLATE/skill_run_feedback.yml` for the generated skill and owner. -Copy `.template/generated/.skill-template-feedback/README.md` and `.gitkeep` into the generated repository root before deleting `.template/`. Confirm the git-ignore pattern below is present in the generated repository's `.gitignore`, which it inherits from the template. +The skill-run form requires one factual observation and an explicit public-disclosure confirmation. Agents must search for duplicates, distinguish observation from diagnosis, remove private identities and local context, show the exact public title and body, and receive approval before creating or commenting on an Issue. -```gitignore -.skill-template-feedback/* -!.skill-template-feedback/.gitkeep -!.skill-template-feedback/README.md -``` - -Only `README.md` and `.gitkeep` are tracked. Everything else in the folder stays local and never ships in the skill package. +Use the ignored `tmp/` directory only for disposable private drafts. Remove each draft after review or submission. Do not create `.plans/`, `.skill-template-feedback/`, or another tracked backlog. -Record the practice in the maintenance `AGENTS.md`: when maintaining the generated skill reveals a template gap, capture it in `.skill-template-feedback/` and open an issue or pull request on `TechSpokes/skill-base-template` so future generated skills inherit the fix. +After the repository owner approves this public feedback workflow, create a `feedback` label for the generated repository so the issue form and canonical query can route reports consistently. Label creation changes public repository metadata and therefore remains an explicit setup action. ## Final Verification @@ -184,6 +180,7 @@ Before declaring cleanup complete, verify: - `.template/` is absent. - `.plans/` is absent. +- `.skill-template-feedback/` is absent. - `README.md` describes the generated skill. - `AGENTS.md` describes maintenance mode. - Exactly one `skills//SKILL.md` exists, its names agree, and it does not reference `.template/`. @@ -192,6 +189,6 @@ Before declaring cleanup complete, verify: - `docs/TESTING.md` and `docs/THREAT-MODEL.md` describe the generated skill's actual behavior and capability risks. - Root `INSTALL.md` and `docs/GITHUB-CLI.md` contain the final public identity, complete copyable commands, and no bootstrap placeholders. - All three generated workflows are installed, including the public GitHub CLI install verifier. -- `.skill-template-feedback/` exists with a tracked `README.md` and `.gitkeep`. +- `docs/FEEDBACK.md` and the skill-run issue form route durable feedback to GitHub Issues, while disposable drafts remain ignored under `tmp/`. - Release staging excludes `.intake/`. - Validation passes. diff --git a/.template/bootstrap/repository-shape.md b/.template/bootstrap/repository-shape.md index bc62d85..86a8827 100644 --- a/.template/bootstrap/repository-shape.md +++ b/.template/bootstrap/repository-shape.md @@ -27,7 +27,6 @@ skill-repository/ |-- README.md |-- .intake/ |-- .template/ -|-- .plans/ |-- skills/ |-- tests/ |-- docs/ @@ -36,7 +35,7 @@ skill-repository/ `-- .github/ ``` -In bootstrap mode, `.template/` is present and `AGENTS.md` points agents to `.template/bootstrap/`. The template also ships `.plans/`, its own maintenance backlog, which is removed during cleanup. +In bootstrap mode, `.template/` is present and `AGENTS.md` points agents to `.template/bootstrap/`. GitHub Issues owns template maintenance state instead of copying a tracked backlog into every generated repository. Rationale: Bootstrap instructions need to be discoverable during construction, but visibly temporary so agents know they must not package or preserve them. @@ -71,7 +70,6 @@ skill-name/ |-- CHANGELOG.md |-- LICENSE |-- .intake/ -|-- .skill-template-feedback/ |-- INSTALL.md |-- skills/ |-- tests/ @@ -83,7 +81,7 @@ skill-name/ Maintenance-mode `AGENTS.md` must no longer describe bootstrap. It must describe how future agents maintain the generated skill. -`.skill-template-feedback/` is the local channel for routing template gaps back upstream. Only its `README.md` and `.gitkeep` are tracked; everything else stays local. +GitHub Issues owns durable feedback and maintenance state. Agents may use the ignored `tmp/` directory for a disposable private draft, but they remove it after exact public review or submission instead of maintaining a second local queue. Rationale: The closest instruction file becomes the future agent's operating frame. If it still describes bootstrap, future maintenance can drift toward rebuilding instead of preserving. diff --git a/.template/generated/.github/instructions/writing.instructions.md b/.template/generated/.github/instructions/writing.instructions.md new file mode 100644 index 0000000..e474487 --- /dev/null +++ b/.template/generated/.github/instructions/writing.instructions.md @@ -0,0 +1,18 @@ +--- +applyTo: "**/*.md" +--- + +# Writing Instructions + +Preserve the author's meaning, vocabulary, authority boundaries, evidence status, and uncertainty before improving style. + +- Put one idea in each paragraph or list item. +- Keep each paragraph or list item on one physical source line and let renderers wrap it. +- Name the actor and action when responsibility or permission matters. +- Prefer direct verbs and concrete nouns over dense label chains. +- Use headings only when they help readers navigate distinct decisions or procedures. +- Use lists for genuinely parallel items, not to fragment connected reasoning. +- Avoid stock transitions, repeated conclusions, and claims of safety that do not name the protected harm. +- Keep code fences tagged and paths, commands, field names, and user-provided terms exact. + +Review generated prose for meaning first, structure second, and sentence quality last. Do not rewrite merely to make the text sound different. diff --git a/.template/generated/.skill-template-feedback/.gitkeep b/.template/generated/.skill-template-feedback/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/.template/generated/.skill-template-feedback/README.md b/.template/generated/.skill-template-feedback/README.md deleted file mode 100644 index 1dfca23..0000000 --- a/.template/generated/.skill-template-feedback/README.md +++ /dev/null @@ -1,9 +0,0 @@ -# Skill template feedback - -This folder is a local staging area for notes and artifacts about the template this skill was generated from, [TechSpokes/skill-base-template](https://github.com/TechSpokes/skill-base-template). - -When maintaining this skill reveals a gap in the template, for example an outdated default, a missing safeguard, or an unclear instruction, capture it here, then surface it upstream as an issue or a pull request so future generated skills inherit the fix. - -The contents of this folder are git-ignored on purpose. Only this `README.md` and a `.gitkeep` are tracked, so the convention travels with the repository while the working notes stay local. Nothing in this folder ships in the skill package. - -A file named `SKILL-REPO-UPGRADE-GUIDE.md` placed here is a useful local artifact: a portable, skill-agnostic checklist for bringing other template-generated repositories up to the current template baseline. Build it from the template's latest release and CHANGELOG, and apply each item through this repository's pull-request flow. diff --git a/.template/generated/AGENTS.md b/.template/generated/AGENTS.md new file mode 100644 index 0000000..bc94707 --- /dev/null +++ b/.template/generated/AGENTS.md @@ -0,0 +1,60 @@ +# Agent Instructions for + +## Summary + +Maintain `` so future agents can perform `` reliably while preserving ``. + +## Read Depth + +Read `skills//SKILL.md` and every affected direct reference before changing runtime behavior. Read all registered fixtures and `docs/TESTING.md` before changing activation, workflow order, output behavior, safety, handoff, or progressive disclosure. Read `docs/THREAT-MODEL.md` before changing access, mutation, automation, private-derived public output, or security controls. + +## Product and Maintenance Goals + +The product goal is ``. + +The maintenance goal is to keep the skill portable, understandable, secure, testable, and releasable without depending on bootstrap history or private source context. + +## Hard Constraints + +- Preserve applicable system, user, organization, and repository instructions. +- Keep the canonical runtime under `skills//` and maintenance fixtures under root `tests/`. +- Require explicit authority for mutation, administration, destruction, publication, and access expansion. +- Do not commit credentials, raw private intake, local paths, or temporary drafts. +- Exclude `.intake/`, `.git/`, `.idea/`, `dist/`, and `tmp/` from release packages. +- Keep package versions synchronized with the changelog, manifests, version documentation, and release notes. + +## Must-Read Documents + +- `skills//SKILL.md` owns runtime behavior. +- `docs/ARCHITECTURE.md` owns durable structure and the canonical runtime map. +- `docs/TESTING.md` owns validation and behavioral evidence. +- `docs/THREAT-MODEL.md` owns capability and security boundaries. +- `docs/RELEASING.md` owns how changes land and releases are cut. +- `docs/FEEDBACK.md` owns public feedback intake and routing. + +## Workspace and Authority + +Treat this repository as the implementation workspace unless the user authorizes another exact target and action. Treat other repositories as evidence sources until separately authorized for mutation. Use the ignored `tmp/` directory for disposable drafts and remove them when they are no longer needed. + +## Canonical Files + +- `skills//SKILL.md` is the runtime entry point. +- `skills//references/` contains focused runtime guidance. +- `tests/fixtures/` and `tests/evals/cases.json` define maintained behavior contracts. +- `docs/` contains architecture, testing, threat, release, and feedback guidance. +- `packaging/` and `scripts/` own release delivery. + +## Required Checks + +Run after every product change: + +```bash +npm run validate +npm run package -- vX.Y.Z +``` + +Use the intended release tag when release behavior or package contents change, and run every additional verification required by `docs/RELEASING.md`. + +## Change Boundaries + +Use a branch and pull request. Do not push directly to the protected default branch. Update runtime, affected references, fixtures, docs, manifests, changelog, and release notes as one coherent change. Keep GitHub issue and pull-request state in GitHub rather than copying a second backlog into repository files. diff --git a/CHANGELOG.md b/CHANGELOG.md index 0059709..57308f8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ - Make GitHub CLI delivery a release gate with exact-tag installation, published installation, previous-release update testing, and installed-tree equality checks. - Normalize repository text to LF, reject escaped generated workflow expressions, and keep active and generated workflows on the same Node setup action. - Add a generated evaluation registry with activation, workflow, adversarial, and agent-surface drift fixtures plus testing and threat-model guidance. +- Make GitHub Issues the only durable template backlog and skill-run feedback surface, remove inherited planning and feedback folders, and add generated maintenance and writing guidance. - Replace the incompatible `src/SKILL.md` source with one standard `skills//SKILL.md` tree and keep maintenance fixtures outside the installed runtime. - Add GitHub CLI publisher validation, public install verification, checksums, attestations, root installation guidance, beginner orientation, and a focused runtime update scaffold. - Make validation, packaging, archive fallback, and installed tree verification discover the generated skill dynamically and remain portable across operating systems. diff --git a/docs/FEEDBACK.md b/docs/FEEDBACK.md new file mode 100644 index 0000000..1a06bf2 --- /dev/null +++ b/docs/FEEDBACK.md @@ -0,0 +1,30 @@ +# Feedback + +## Goal + +Route useful observations from real skill runs into the owning GitHub repository without maintaining a second local feedback queue. + +## Canonical Surface + +GitHub Issues owns durable feedback state. Use the skill-run feedback form for observations, the bug form for reproducible defects, the feature form for proposed improvements, Discussions for questions, and the private security path for sensitive findings. + +The reporter only needs to provide one factual observation. Maintainers or authorized agents may add intended outcome, impact, environment, evidence, hypothesis, and related cases when those facts are known and useful. + +## Agent Workflow + +1. Preserve the user's factual observation and intended outcome. +2. Search existing Issues for a duplicate. +3. Separate observation from diagnosis and label uncertainty. +4. Remove credentials, private identities, repository relationships, local paths, restricted screenshots, and unnecessary raw logs. +5. Show the exact public title and body to the user and receive approval before creating or commenting on an Issue. +6. Verify the created or updated Issue and report its link. + +Use the ignored `tmp/` directory only when a disposable private draft is necessary. Remove the draft after review or submission. Do not create `.plans`, `.skill-template-feedback`, or another tracked backlog. + +## Repository Setup + +The issue form requests one observation and an explicit public-disclosure confirmation. During generated-repository setup, create a `feedback` label only after the repository owner approves the public feedback workflow. Labels are navigation aids; GitHub Issues remains the source of truth when the label is absent or changed. + +## Security + +Do not place vulnerability details, credentials, private data, or exploit material in a public issue. Follow `SECURITY.md` for private reporting and preserve evidence without expanding disclosure. diff --git a/scripts/validate-skill.mjs b/scripts/validate-skill.mjs index 56c35a1..9de1d8d 100644 --- a/scripts/validate-skill.mjs +++ b/scripts/validate-skill.mjs @@ -325,6 +325,63 @@ function validateWorkflowMode() { } } +/** Validates the issue-centered maintenance and communication scaffold. + * @returns {void} + * @sideEffects Appends contract violations to the shared failure collection. + * @constraints GitHub Issues owns durable feedback state; repository files may provide forms and instructions but not a second backlog. + * @why #16 replaces inherited planning and feedback folders with one owner-maintained coordination surface. + */ +function validateMaintenanceScaffold() { + if (exists(".plans")) { + fail("The template must not copy a .plans backlog into generated repositories."); + } + if (exists(".skill-template-feedback") || exists(".template/generated/.skill-template-feedback")) { + fail("Feedback must route through GitHub Issues instead of .skill-template-feedback."); + } + if (readText(".gitignore").includes(".skill-template-feedback")) { + fail(".gitignore still carries the removed feedback-folder convention."); + } + + for (const file of ["docs/FEEDBACK.md", ".github/ISSUE_TEMPLATE/skill_run_feedback.yml"]) { + if (!exists(file)) { + fail(`Missing issue-centered feedback file ${file}.`); + } + } + + const feedback = readText("docs/FEEDBACK.md"); + for (const expected of ["one factual observation", "exact public title and body", "ignored `tmp/` directory", "GitHub Issues remains the source of truth"]) { + if (!feedback.includes(expected)) { + fail(`docs/FEEDBACK.md is missing feedback contract: ${expected}.`); + } + } + + const issueForm = readText(".github/ISSUE_TEMPLATE/skill_run_feedback.yml"); + for (const expected of ["id: observation", "required: true", "id: privacy", "credentials, private identities, local paths"]) { + if (!issueForm.includes(expected)) { + fail(`Skill-run feedback form is missing contract: ${expected}.`); + } + } + + if (bootstrapMode) { + for (const file of [".template/generated/AGENTS.md", ".template/generated/.github/instructions/writing.instructions.md"]) { + if (!exists(file)) { + fail(`Missing generated maintenance scaffold ${file}.`); + } + } + const generatedAgents = readText(".template/generated/AGENTS.md"); + for (const heading of ["Summary", "Read Depth", "Product and Maintenance Goals", "Hard Constraints", "Must-Read Documents", "Workspace and Authority", "Canonical Files", "Required Checks", "Change Boundaries"]) { + if (!generatedAgents.includes(`## ${heading}`)) { + fail(`Generated maintenance AGENTS.md is missing section ${heading}.`); + } + } + return; + } + + if (/<(?:Skill Name|skill-name|primary outcome|durable benefit)/.test(readText("AGENTS.md"))) { + fail("Maintenance AGENTS.md still contains generated scaffold placeholders."); + } +} + /** * Validates the reusable GitHub CLI source and release delivery contract. * @returns {void} @@ -476,6 +533,7 @@ validateManifests(); validateReleaseNotes(); validatePackagingBoundaries(); validateWorkflowMode(); +validateMaintenanceScaffold(); validateDeliveryContract(); validateReleaseMarkdownWrapping();