diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml index cf004c1..004b829 100644 --- a/.github/FUNDING.yml +++ b/.github/FUNDING.yml @@ -1 +1,7 @@ github: TechSpokes +# You can also add other platforms: +# open_collective: your-collective +# patreon: your-patreon +# ko_fi: your-kofi +# custom: +# - 'https://www.techspokes.com' diff --git a/.intake/README.md b/.intake/README.md index 9f3c27b..760d491 100644 --- a/.intake/README.md +++ b/.intake/README.md @@ -14,6 +14,8 @@ Place all user-provided source material or skill ideas in this folder. Agents treat this folder as source material. They infer the intended skill, extract durable knowledge, build `src/SKILL.md`, create references, update documentation, and prepare release packaging. +Agents may create `research/`, `experiments/`, and `playground/` subfolders here to hold evidence gathered while resolving gaps. + Intake files are never release artifacts. They may be transformed into skill references when the content is useful and safe to publish. When this folder is empty or insufficient, agents should assess what is missing before skill construction. They may resolve gaps by extracting evidence, making low-risk assumptions, inspecting local tools or docs, creating disposable experiments, narrowing scope, asking concise questions, or stopping before build work when construction would require fabrication. diff --git a/.plans/0000-backlog.md b/.plans/0000-backlog.md index 058badf..d812174 100644 --- a/.plans/0000-backlog.md +++ b/.plans/0000-backlog.md @@ -14,6 +14,8 @@ All five issues originate from one descendant repository, [skill-postgres-intros | [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 @@ -23,6 +25,10 @@ Plan 0008 is partially implemented. The branch-and-pull-request flow is document 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. diff --git a/.plans/0009-community-and-sponsorship.md b/.plans/0009-community-and-sponsorship.md new file mode 100644 index 0000000..2a7e990 --- /dev/null +++ b/.plans/0009-community-and-sponsorship.md @@ -0,0 +1,39 @@ +# 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 new file mode 100644 index 0000000..e7128a3 --- /dev/null +++ b/.plans/0010-bootstrap-instruction-improvements.md @@ -0,0 +1,69 @@ +# 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 new file mode 100644 index 0000000..0f54831 --- /dev/null +++ b/.plans/0011-distill-authoring-guidance.md @@ -0,0 +1,35 @@ +# 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/.template/bootstrap/build-skill-from-intake.md b/.template/bootstrap/build-skill-from-intake.md index f25bf77..a586440 100644 --- a/.template/bootstrap/build-skill-from-intake.md +++ b/.template/bootstrap/build-skill-from-intake.md @@ -1,6 +1,6 @@ # Build Skill From Intake -This file is part of the TechSpokes Skill Base Template bootstrap system. It distills TechSpokes guidance on agent skill creation, instruction design, and repository maintenance into an actionable workflow. +This file is the end-to-end workflow an agent follows to build a skill from intake. ## Goal @@ -76,7 +76,7 @@ Use `.template/bootstrap/intake-adequacy-and-resolution.md` for the full procedu If intake is adequate, record the assessment and continue to Phase 1. -If intake is missing build-critical evidence, resolve the gap through extraction, inference, safe discovery, scoped experiments, scope narrowing, minimal human clarification, or a documented stop. Do not start `src/SKILL.md` until the build readiness gate passes. +If intake is missing build-critical evidence, resolve the gap through extraction, inference, safe discovery, scoped experiments, scope narrowing, minimal human clarification, or a documented stop. Do not start `src/SKILL.md` until the build readiness gate passes and the agent's understanding is confirmed with the user. Required temporary artifacts: @@ -115,6 +115,10 @@ The design note is temporary. Move durable architecture information into `docs/A Rationale: The design note gives the bootstrap agent a place to reason before committing to permanent files. Durable decisions move into docs because future maintainers need the why, not the temporary scratchpad. +Before Phase 3, confirm this design synthesis with the user. Present the skill candidate, goal, activation and non-activation boundary, workflow outline, and key assumptions, and ask the user to confirm or correct them. See the alignment confirmation step in `.template/bootstrap/intake-adequacy-and-resolution.md`. Do not begin construction until the direction is confirmed. + +Rationale: The agent has now synthesized a design from intake and its own inferences. Confirming the direction before construction keeps the skill aligned with the user's intent and makes a correction cheap relative to rebuilding. + ## Phase 3: Build The Skill Product Build the product surface in `src/`. @@ -230,13 +234,18 @@ 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. +- 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. + Rationale: Cleanup converts the repository's identity. Before cleanup, the repository is a skill factory. After cleanup, it is the skill. ## Completion Criteria diff --git a/.template/bootstrap/cleanup-and-boundaries.md b/.template/bootstrap/cleanup-and-boundaries.md index 2c0aeb4..c7eb4bf 100644 --- a/.template/bootstrap/cleanup-and-boundaries.md +++ b/.template/bootstrap/cleanup-and-boundaries.md @@ -1,7 +1,5 @@ # Cleanup And Boundaries -This file is a distilled operational version of TechSpokes guidance on repository handoff, authority boundaries, and maintenance-mode transition. - ## Goal Convert a generated repository from bootstrap mode to maintenance mode without leaking bootstrap instructions into the final skill. @@ -62,6 +60,8 @@ The final `AGENTS.md` must support future maintenance. It should include: - The generated skill's maintenance goal. +- The skill's core principles, each with the rationale it protects. +- A decision stance for how a future agent should act when the exact instruction does not fit. - Required validation commands. - A short statement of how changes land, pointing to `docs/RELEASING.md`. - Skill reference organization rules. @@ -70,6 +70,8 @@ It should include: Make `docs/RELEASING.md` the single source for how changes land and how a release is cut. Point `AGENTS.md` and `CONTRIBUTING.md` to it rather than repeating the steps, so the documents never drift apart. +The core principles and the decision stance are how the skill's goals and values reach future agents who make local decisions. State each principle as a durable commitment with its reason. State the decision stance concretely: diagnose the situation against the skill's goal, weigh the local context, and bring the decision to the user rather than acting alone or silently deferring. + The final `AGENTS.md` should explain why important boundaries exist. A future agent can adapt a rule responsibly only when it understands the value the rule protects. ## GitHub Community File Handoff diff --git a/.template/bootstrap/cross-intelligence-communication.md b/.template/bootstrap/cross-intelligence-communication.md index c09030f..42a92ac 100644 --- a/.template/bootstrap/cross-intelligence-communication.md +++ b/.template/bootstrap/cross-intelligence-communication.md @@ -1,10 +1,10 @@ # Cross-Intelligence Communication Rules -This file is a distilled operational version of TechSpokes cross-intelligence communication guidance for generated skill repositories. +This file gives the communication rules for writing instruction files that future agents, humans, and tools can all follow. ## Goal -Preserve the practical lessons from the local communication theory files while building and maintaining generated skill repositories. +Write generated repository instructions that survive transfer across humans, LLM agents, and tools, under different context windows and tool permissions. ## Core Rationale @@ -49,11 +49,9 @@ When generating instructions for agents, always encode: If one of these is missing, future agents may comply with the surface form while breaking the intended system behavior. -## Source Theory Position +## Related Guidance -These rules are adapted from TechSpokes research on cross-intelligence communication, directive-file design, README structure, and problem framing. - -The full research files are not vendored into this template. They are too large and exploratory for bootstrap context. Use `.template/bootstrap/theory-context.md` as the operational summary and apply the practical rules below. +For the reasoning model behind these rules, see `.template/bootstrap/theory-context.md`. Apply the practical rules below when writing any instruction file. ## Core Principles @@ -178,6 +176,8 @@ Do not preserve bootstrap rationale in generated repositories unless it helps ma When rewriting `AGENTS.md` for maintenance mode: - State the generated skill maintenance goal in the summary. +- State the skill's core principles, each with the rationale it protects. +- State a decision stance that tells a future agent how to act when the exact instruction does not fit. - List hard constraints before guidelines. - Define specialized terms early. - Include required validation commands. @@ -187,6 +187,16 @@ When rewriting `AGENTS.md` for maintenance mode: Carry the rationale for any rule that future agents may need to adapt. A maintenance agent should know not only that release artifacts exclude intake, but also that the exclusion protects privacy and prevents raw source material from being mistaken for a polished skill resource. +The core principles and the decision stance are how goals and values reach future agents who make local decisions. State each principle as a durable commitment with its reason, so an agent can tell what to preserve when conditions differ. State the decision stance as a concrete way to act under uncertainty: diagnose the situation against the skill's goal, weigh the local context, and bring the decision to the user rather than acting alone or silently deferring. A rule tells an agent what to do; the principles and stance tell it how to decide when no rule fits. + +Give the generated `AGENTS.md` a predictable shape, in this order: a title naming the folder and its purpose; a Summary that leads with the highest-value guidance; Must-follow rules as hard constraints; Must-read documents as paths each paired with why it matters; Agent guidelines as prose preferences; Context as background that holds no requirements; and optional References. + +Put read-depth guidance in the Summary, so an agent under context limits knows how much to read. Say when the Summary alone is enough and what to do if the full file cannot be loaded. + +Keep the file short, targeting under 100 lines. Move overflow into `docs/` or references and point to it from Must-read documents, because a long file is more likely to be loaded only in part. + +Write `AGENTS.md` only when a standalone Summary would be useful. An absent file is better than a low-value one. + ## Generated README Rules When rewriting `README.md` for the generated skill: diff --git a/.template/bootstrap/intake-adequacy-and-resolution.md b/.template/bootstrap/intake-adequacy-and-resolution.md index eba9b33..78ade26 100644 --- a/.template/bootstrap/intake-adequacy-and-resolution.md +++ b/.template/bootstrap/intake-adequacy-and-resolution.md @@ -207,6 +207,17 @@ Stop before building when the remaining gap would force fabrication, unsafe acce State the blocking gap and the smallest input that would unblock the work. +## Asking High-Value Questions + +When local resolution is exhausted and a question is necessary, make it count. + +- Ask only about genuine capability gaps, conflicts, priorities, or permissions. A gap you can extract, infer, or discover is research you skipped, not a question. +- Phrase a question as a confirm-or-refute test of a specific assumption, not an open prompt. Say what would confirm it and what would refute it. +- When the intake reads more than one way, list the competing interpretations and ask the one question whose answer separates the most of them. +- Separate what cannot change from what merely should not. Only fixed constraints can block a build. +- Do not turn nearby mentions or ordering in the intake into a requirement, and do not assume a request for one case applies to every case. Confirm intent first. +- After each answer, recompute the remaining gaps. A resolved blocker can shift the goal and reveal new ones. + ## Common Intake States ### Empty Intake @@ -251,6 +262,26 @@ Require stronger evidence for domains involving medicine, law, finance, security Do not use low-confidence assumptions to pass the build readiness gate in high-risk areas. +## Alignment Confirmation + +After the build readiness gate passes and before writing `src/SKILL.md`, confirm the agent's synthesized understanding with the user. The purpose is alignment, not design delegation. + +Present a short synthesis the user can confirm or correct in one reading: + +- The skill candidate and its goal in one or two sentences. +- The activation and non-activation boundary. +- The core workflow in outline. +- The key assumptions the readiness decision depends on, labeled as assumptions. +- Anything narrowed, deferred, or resolved from a conflict. + +Ask the user to confirm or correct this synthesis. A correction is cheap; a wrong skill is expensive. If the user corrects it, revise the design and confirm the corrected direction before construction begins. + +Scale the step to how much the readiness decision rested on the agent's own guesses. When intake was explicit and the decision rested on direct evidence with no material assumptions, a brief restatement is enough. When the decision rested on inference, scope narrowing, or conflict resolution, confirmation matters more, because the agent is acting on its interpretation rather than on stated intent. + +This step is distinct from the `Ask` rung of the resolution ladder. `Ask` resolves a specific blocking gap during resolution. Alignment confirmation validates the agent's overall interpretation after resolution, so construction starts from a shared understanding. + +Do not turn this into a questionnaire. Present synthesized understanding, not a list of design questions. The agent does the design work; the user confirms the direction. This keeps the step clear of the `Questionnaire Transfer` pitfall. + ## Required Temporary Artifacts Create these files under `.template/state/` while bootstrap mode is active: @@ -312,5 +343,6 @@ Phase 0 is complete when: - Blocking gaps have been resolved, narrowed, asked, or stopped. - Unsafe discovery has been avoided or approved. - Build readiness has a clear decision. +- The agent's synthesized understanding has been confirmed with the user. - Any created evidence is stored under `.intake/`. - Any temporary reasoning is stored under `.template/state/`. diff --git a/.template/bootstrap/repository-shape.md b/.template/bootstrap/repository-shape.md index 7b4ecf3..fb2760e 100644 --- a/.template/bootstrap/repository-shape.md +++ b/.template/bootstrap/repository-shape.md @@ -1,7 +1,5 @@ # Repository Shape -This file is a distilled operational version of TechSpokes repository-structure guidance for agent-maintained skill packages. - ## Goal Define the repository states before bootstrap, during bootstrap, and after cleanup. @@ -29,6 +27,7 @@ skill-repository/ |-- README.md |-- .intake/ |-- .template/ +|-- .plans/ |-- src/ |-- docs/ |-- packaging/ @@ -36,7 +35,7 @@ skill-repository/ `-- .github/ ``` -In bootstrap mode, `.template/` is present and `AGENTS.md` points agents to `.template/bootstrap/`. +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. Rationale: Bootstrap instructions need to be discoverable during construction, but visibly temporary so agents know they must not package or preserve them. @@ -68,6 +67,7 @@ skill-name/ |-- CHANGELOG.md |-- LICENSE |-- .intake/ +|-- .skill-template-feedback/ |-- src/ |-- docs/ |-- packaging/ @@ -77,6 +77,8 @@ 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. + 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. ## Release Artifact Shape diff --git a/.template/bootstrap/skill-quality-standard.md b/.template/bootstrap/skill-quality-standard.md index 870b001..70829fd 100644 --- a/.template/bootstrap/skill-quality-standard.md +++ b/.template/bootstrap/skill-quality-standard.md @@ -1,7 +1,5 @@ # Skill Quality Standard -This file is a distilled operational version of TechSpokes skill packaging, Markdown form engineering, and directive-file quality guidance. - ## Goal Define the minimum quality bar for skills generated from this template. @@ -87,6 +85,10 @@ The install section links to the repository's Releases page and names the three Keep clone and maintainer commands such as `npm run validate` and `npm run package` out of the opening. Move conceptual and internal detail into `docs/` and link to it from the README. The install locations in the README and in `docs/INSTALL.md` must agree. +Required elements: an H1 that is the skill name, a first paragraph that says what the skill does without relying on another file, and the license stated or linked. Front-load anything decision-critical, such as prerequisites or warnings, because readers consume the page in part. + +Avoid walls of text, nested lists, horizontal rules, and bold used as a heading. Tag every code fence with a language, give images alt text, and flag any destructive or privileged command right before it. Aim for roughly 100 to 200 lines; treat 500 or more as a signal to move detail into `docs/`. + Rationale: A normal user landing on a published skill should be able to download a release and install it without cloning or Node. Leading with build instructions hides the skill's value behind maintainer concerns. ## Reference Rules @@ -103,6 +105,12 @@ Use `src/test-fixtures/` for prompts or examples that verify the skill after cha Rationale: Fixtures preserve behavioral expectations across maintenance changes. They are evidence that the skill still works, not part of normal execution. +## Script Rules + +When a generated skill ships runnable scripts, comment them to explain why the code does what it does and any non-obvious constraints, not to narrate what each line does. Prefer structured docblock tags over prose so the comments stay parseable and stay out of search noise. + +Rationale: A future agent maintaining the skill cannot ask the original author. Comments that protect intent and constraints survive that handoff; line-by-line narration does not. + ## Cross-Intelligence Communication Rules Write for humans, LLM agents, and tools. diff --git a/.template/bootstrap/theory-context.md b/.template/bootstrap/theory-context.md index dff6611..2d10038 100644 --- a/.template/bootstrap/theory-context.md +++ b/.template/bootstrap/theory-context.md @@ -1,18 +1,12 @@ # Theory Context For Bootstrap Agents -This is a distilled operational version of TechSpokes cross-intelligence communication and problem-framing research. It is adapted for bootstrap agents using this public template and is not the full source theory. +This file gives the reasoning model the bootstrap workflow relies on. Use it to make skill-design and instruction decisions that hold up when no specific rule applies. ## Goal -Give bootstrap agents the reasoning model behind this template without requiring them to load large research files. +Carry the reasoning model in compact operational form, so design choices preserve purpose rather than only following steps. -## Decision - -Do not vendor the full theory files into generated repositories. Use this adapted operational summary instead. - -The original research files are long, exploratory, and partly project-local. Including them as-is would increase context load, expose non-template research material, and make bootstrap agents sort theory from action. The useful part for this template is the operating model below. - -## Values Preserved From The Theory +## Values - Preserve purpose over literal wording. - Make implicit intent explicit. @@ -52,7 +46,7 @@ High-risk terms in this template include: - `maintenance` - `authority` -Define these terms when they affect behavior. +Define these terms when they affect behavior. The `AGENTS.md` Definitions section carries the meanings this template uses. The reason: an agent can confidently choose a plausible meaning that is wrong for this repository. @@ -94,6 +88,46 @@ Use different verification modes for different risks: The reason: no single intelligence type catches every failure mode. +## How Meaning Survives Transport + +These principles explain why the rules above matter when an instruction crosses between humans, agents, and tools. + +### Write For One-Way Delivery + +A directive file is read later by a recipient who cannot ask you to clarify. Anticipate the questions a future agent would ask. + +The reason: a gap you leave becomes a silent wrong guess, not a question. + +### Protect The Weakest Stage + +Meaning passes through many stages from intent to action, and the weakest stage caps the result. The stage that fails most often is the one where the goal was never stated. + +The reason: stating the goal raises fidelity more than polishing already-clear rules. + +### Track Goal Survival Separately From Rule Survival + +Rules often arrive intact while the reason behind them is lost, which produces confident but brittle compliance. Check whether the purpose survived, not only whether the steps did. + +The reason: an agent that keeps the rule but loses the goal defends the wrong behavior when conditions change. + +### Treat Distortion As Worse Than Loss + +Missing information leaves a visible gap. A distorted instruction looks complete, parses cleanly, and produces confident wrong action that passes output checks. + +The reason: a result that ran and looked right is not evidence the instruction was understood. + +### Design For The Boundary Being Crossed + +Each handoff loses something specific. Prose aimed at a human invites unwarranted trust from an agent; a rule aimed at a tool drops what is not expressible as a rule; paraphrase between agents drifts toward generic meaning. + +The reason: write for the specific recipient and boundary, not for an AI in general. + +### Repeat Critical Constraints On Purpose + +Repeating a critical constraint where it is needed raises the chance it is processed at least once under partial loading. + +The reason: deduplication assumes full reading, which rarely holds for agents. + ## How To Use This File Read this file before designing or rewriting generated repository instructions. diff --git a/AGENTS.md b/AGENTS.md index 904c731..de678d6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -42,7 +42,7 @@ When instructions appear to conflict, choose the option that best preserves the - Treat `.intake/` as the only user-authored source area. - Read `.template/bootstrap/build-skill-from-intake.md` before changing skill files. - Run the intake adequacy gate before skill design, even when `.intake/` is empty or only contains a short idea. -- Do not start `src/SKILL.md` until the build readiness gate passes. +- Do not start `src/SKILL.md` until the build readiness gate passes and the agent's synthesized understanding is confirmed with the user. - Treat `.template/` as bootstrap control instructions, not domain source material. - Do not copy `.template/` content into `src/` unless the content is explicitly transformed into generic maintenance guidance. - Exclude `.template/`, `.intake/`, `tmp/`, `dist/`, `.git/`, and `.idea/` from release artifacts. diff --git a/CHANGELOG.md b/CHANGELOG.md index 87e31a5..a8206e1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,19 @@ - No unreleased changes. +## [v1.3.0] + +- Add documented sponsorship platform examples to `.github/FUNDING.yml`. +- Enable Discussions and disable Projects and Wiki on the template repository. +- Require a core-principles-and-decision-stance section in the generated `AGENTS.md`, so the skill's goals and values reach future agents that make local decisions. +- Add an alignment-confirmation step to the exploratory phase: after the build readiness gate and before construction, the agent confirms its synthesized understanding with the user, distinct from the resolution ladder's `Ask` rung. +- Gate Phase 3 construction on the confirmed design synthesis in the bootstrap workflow, and add the matching must-follow rule to `AGENTS.md`. +- Reframe the bootstrap instruction files to address the executing agent directly, keeping authorship attribution in `docs/PROVENANCE.md`. +- Document `.plans/` and `.skill-template-feedback/` in the repository-shape trees and the Phase 7 cleanup steps for consistency. +- Distill the AGENTS.md and README authoring guidance into the bootstrap docs: the generated `AGENTS.md` section shape, read-depth and under-100-line size guidance, and README required elements, anti-patterns, and sizing. +- Add cross-intelligence transport principles to the reasoning model: one-way delivery, the weakest stage, goal survival, distortion, boundary-specific design, and deliberate redundancy. +- Add an "Asking High-Value Questions" guide to the exploratory phase and a `Script Rules` section for commenting any scripts a generated skill ships. + ## [v1.2.0] - Pin the generated CI and release workflows to `actions/checkout@v7` and `actions/setup-node@v6`, and use a `v0.0.0` placeholder for the packaging smoke test, so new repositories do not start a major behind or read the smoke-test tag as a real version. diff --git a/docs/VERSION.md b/docs/VERSION.md index 8cfa2d9..70cc51a 100644 --- a/docs/VERSION.md +++ b/docs/VERSION.md @@ -2,7 +2,7 @@ The template starts public release at version `1.0.0`. -The current template version is `1.2.0`. +The current template version is `1.3.0`. Generated skill repositories should reset or continue versioning according to the generated skill's release policy. diff --git a/docs/releases/v1.2.0.md b/docs/releases/v1.2.0.md index 0dec9d7..ffd1ede 100644 --- a/docs/releases/v1.2.0.md +++ b/docs/releases/v1.2.0.md @@ -1,6 +1,6 @@ # Skill Base Template v1.2.0 -This release applies five maintenance fixes reported from a descendant repository generated by this template, so future generated repositories inherit current defaults, correct install instructions, cleaner packages, repository hardening, and an upstream feedback channel. +This release applies five maintenance fixes so repositories generated from this template inherit current defaults, correct install instructions, cleaner packages, repository hardening, and a built-in channel for routing template gaps back upstream. ## Highlights @@ -14,9 +14,9 @@ This release applies five maintenance fixes reported from a descendant repositor ## Why It Matters -A repository generated from this template now starts on current action majors, documents install locations that the tools actually read, and produces release packages without empty placeholder folders. These were day-one defects that each descendant otherwise had to find and fix by hand. +A repository generated from this template now starts on current action majors, documents install locations that the tools actually read, and produces release packages without empty placeholder folders. These were day-one defects a generated repository otherwise had to find and fix by hand. -The template also now prescribes the protections it expects: branch protection, secret scanning, push protection, and Dependabot security updates, with a single documented release process. The new `.skill-template-feedback/` folder turns the one-off, manual feedback that produced this release into a repeatable loop from descendants back to the template. +The template also now prescribes the protections it expects: branch protection, secret scanning, push protection, and Dependabot security updates, with a single documented release process. The new `.skill-template-feedback/` folder gives a generated repository a standard channel to route template gaps back upstream, turning ad hoc feedback into a repeatable loop. ## Notes diff --git a/docs/releases/v1.3.0.md b/docs/releases/v1.3.0.md new file mode 100644 index 0000000..49a6f65 --- /dev/null +++ b/docs/releases/v1.3.0.md @@ -0,0 +1,29 @@ +# Skill Base Template v1.3.0 + +This release improves the template's community and sponsorship configuration and strengthens the bootstrap instructions for transmitting goals and values and for confirming alignment with the user before a skill is built. + +## Highlights + +- Add documented sponsorship platform examples to `.github/FUNDING.yml`. +- Enable Discussions and disable Projects and Wiki on the template repository. +- Require a core-principles-and-decision-stance section in the generated `AGENTS.md`. +- Add an alignment-confirmation step to the exploratory phase, before skill construction. +- Gate construction on the confirmed design synthesis, with a matching must-follow rule in `AGENTS.md`. +- Reframe the bootstrap instruction files to address the executing agent directly. +- Distill more of the authoring and reasoning guidance into the bootstrap docs, including AGENTS.md and README shape, transport principles, and a questioning guide. + +## Why It Matters + +The template now carries the community and sponsorship configuration it expects a generated repository to use, so the setup a new repository inherits is one the template itself runs. + +The bootstrap guidance now requires every generated `AGENTS.md` to state the skill's core principles and a 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. This is how a skill's goals and values reach future agents that must make local decisions, rather than leaving it to chance. + +The exploratory phase previously moved from intake adequacy straight into construction. When the readiness decision rested on the agent's own inferences, the skill could start misaligned with the user's intent. The new alignment-confirmation step has the agent present its synthesized understanding for confirmation or correction before it builds, while staying clear of pushing design work back to the user. + +The bootstrap instruction files now open by addressing the executing agent and its task rather than describing the template's origins. The first thing the agent reads orients it to what to do, which is how the instructions transmit their intent under partial reading and variable context. + +The bootstrap docs also carry more distilled authoring guidance: a predictable shape and size target for the generated `AGENTS.md`, required elements and anti-patterns for the README, transport principles for why the rules hold across humans, agents, and tools, and a guide to asking high-value clarifying questions. The guidance is distilled in the template's own voice; the underlying sources are credited in `docs/PROVENANCE.md`. + +## Notes + +Release tag: `v1.3.0`. diff --git a/package.json b/package.json index e7bf5fe..e96cc07 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "skill-base-template", - "version": "1.2.0", + "version": "1.3.0", "private": true, "type": "module", "scripts": {