From bc4986775b1f68ee27931ccb69d19018b11fb5ec Mon Sep 17 00:00:00 2001 From: pentaxis93 <13393192+pentaxis93@users.noreply.github.com> Date: Tue, 10 Mar 2026 13:27:28 +0000 Subject: [PATCH] docs(contributing): remove skill-creator policy Replace the contributor-facing skill-authoring prescription with tool-agnostic quality standards, delete ADR-0004, and reframe remaining research references as historical context only. Refs #111 --- CHANGELOG.md | 2 +- CONTRIBUTING.md | 50 +++++++------ .../decisions/0004-skill-authoring-system.md | 74 ------------------- docs/research/epic-7-methodology-research.md | 6 +- .../existing-skill-implementations.md | 2 +- .../what-should-groundwork-be-made-of.md | 2 +- 6 files changed, 34 insertions(+), 102 deletions(-) delete mode 100644 docs/architecture/decisions/0004-skill-authoring-system.md diff --git a/CHANGELOG.md b/CHANGELOG.md index f70e79c..118ec98 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -48,7 +48,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). - Renamed `planning` skill to `next-issue`; added separate `plan` skill for design convergence - Reframed sovereignty as a fractal principle (applies at every interface, not just human-agent) - Removed the prescriptive step-script decomposition skill from the curated set and live pipeline docs; rationale recorded in [`docs/research/epic-7-methodology-research.md`](docs/research/epic-7-methodology-research.md). Live methodology docs no longer route work through the deprecated intermediary planning handoff. -- Removed the curated skill-authoring meta-skill from runtime docs/config and adopted external `skill-creator` as the contributor-facing skill-authoring system, so first-session agents only load pipeline-relevant skills. +- Replaced tool-specific skill-authoring policy with tool-agnostic skill acceptance standards in contributor docs, removed ADR-0004, and stripped active local-path authoring prescriptions from project documentation. - Replaced the separate curated manifest plus hardcoded local-skill inventory with one shipped-skill manifest at `skills/skills.toml`, flattened tracked skill paths under `skills/`, and made `groundwork list` follow that manifest order. ### Fixed diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2659942..ceeb13e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -75,28 +75,34 @@ The `origin:` field in `SKILL.md` frontmatter must: - `skills/plan/LICENSE-UPSTREAM` — adapted from OpenAI Codex (Apache-2.0), with itemized derived vs. original elements - `skills/test-first/LICENSE-UPSTREAM` — adapted from obra/superpowers (MIT), with description of preserved portions -## Skill Authoring Boundary - -Groundwork stores the skills it ships, but it does not ship its own -skill-authoring toolchain. Use the external sibling repository -`/home/pentaxis93/src/skill-creator` when you need to: - -- create a new skill -- regenerate an existing Groundwork skill -- evaluate whether a skill change actually improves behavior - -Treat Groundwork as the destination for committed skill outputs and pipeline -documentation: - -1. Do the authoring or regeneration work in `skill-creator` -2. Bring the resulting `SKILL.md` content or curation change back into this repo -3. If the skill adapts upstream material, add a `LICENSE-UPSTREAM` file alongside `SKILL.md` and include an `origin:` field in frontmatter referencing it. See [Upstream Attribution](#upstream-attribution). -4. Update `skills/skills.toml`, `agents.toml`, README/WORKFLOW entries, - ADRs, and CHANGELOG only if the shipped Groundwork inventory or methodology - changes - -Do not add `skill-creator` to `agents.toml` or `skills/skills.toml`. -It is contributor tooling, not part of Groundwork's runtime skill inventory. +## Skill Quality Standards + +Groundwork cares about the quality and compatibility of the skills it ships, +not which authoring tool produced them. A contribution meets the skill +authoring bar when the tracked output is well-formed and integrates cleanly +with the live methodology. + +A repo-tracked skill contribution must: + +- live at `skills//SKILL.md` +- use YAML frontmatter with, at minimum, `name` and `description` +- include `metadata`, `origin`, and `replaces` fields when they apply +- include a co-located `LICENSE-UPSTREAM` file when the skill adapts upstream + material, and reference it from `origin:` metadata +- include a valid `groundwork:` frontmatter block when the skill participates + in runtime pipeline contracts; follow the accepted format in + `docs/architecture/decisions/0002-groundwork-frontmatter-format.md` +- use valid Markdown/plain text encoding and stable relative references so the + skill can be installed and read without local-environment assumptions + +When a skill contribution changes the shipped Groundwork inventory or +methodology, update the corresponding manifest and documentation surfaces in +this repository (`skills/skills.toml`, `agents.toml`, README/WORKFLOW entries, +pipeline docs, ADRs, CHANGELOG) so the tracked project state stays accurate. + +Contributor tooling is not part of Groundwork's runtime skill inventory. Only +add entries to `agents.toml` or `skills/skills.toml` for skills Groundwork +actually ships. ## Agent Workspace Policy diff --git a/docs/architecture/decisions/0004-skill-authoring-system.md b/docs/architecture/decisions/0004-skill-authoring-system.md deleted file mode 100644 index c8d1617..0000000 --- a/docs/architecture/decisions/0004-skill-authoring-system.md +++ /dev/null @@ -1,74 +0,0 @@ -# ADR-0004: Skill Authoring System - -**Status:** Accepted -**Date:** 2026-03-07 - -## Context - -Groundwork is a runtime methodology library. It ships skills that agents load -while doing project work, plus the CLI and documentation that define the -pipeline. It does not need to ship the tooling used to author or evaluate those -skills. - -Issue #42 removed `writing-skills` from Groundwork's runtime docs and config. -That resolved the inventory question but left the authoring question partially -implicit: several docs and issues still treated `writing-skills` as the live -reference for creating or regenerating skills. - -The local sibling repository `/home/pentaxis93/src/skill-creator` now provides -the missing authoring boundary. It is platform-agnostic at the output layer, -supports iterative skill improvement, and includes an evaluation loop. This ADR -records how Groundwork uses it. - -## Decision Drivers - -- Groundwork runtime docs should stay focused on the live methodology pipeline -- Skill authoring is a contributor workflow, not a runtime stage -- The adopted authoring system must produce platform-agnostic skill outputs -- Future sessions need one clear default for skill creation and regeneration -- Groundwork should preserve historical research findings without presenting - removed skills as current guidance - -## Decision - -**Groundwork adopts the external `skill-creator` repository as its -skill-authoring system.** - -Concretely: - -- Use `/home/pentaxis93/src/skill-creator` for creating, regenerating, and - evaluating skills -- Keep authoring guidance in contributor-facing documentation, not in runtime - pipeline docs -- Do not add `skill-creator` to Groundwork's runtime inventory in - `agents.toml` or `skills/skills.toml` -- Treat `writing-skills` as historical research context only, not as an active - Groundwork skill or default authoring reference - -## Consequences - -### Good - -- Contributors and agents have one explicit place to go for skill authoring -- Runtime docs remain about the pipeline Groundwork actually ships -- Historical research can be preserved without confusing present-day guidance - -### Neutral - -- Groundwork now depends on an adjacent repository for authoring workflow, but - not for runtime behavior - -### Bad - -- Contributors need access to a second repository when doing skill-authoring - work -- Authoring workflow changes in `skill-creator` are not versioned inside this - repository - -### Risks - -- If the local `skill-creator` path changes, contributor docs will drift until - updated -- Future research docs could accidentally reintroduce `writing-skills` as live - guidance unless documentation review keeps the historical/current distinction - explicit diff --git a/docs/research/epic-7-methodology-research.md b/docs/research/epic-7-methodology-research.md index 83913da..1ac6dfb 100644 --- a/docs/research/epic-7-methodology-research.md +++ b/docs/research/epic-7-methodology-research.md @@ -401,7 +401,7 @@ It maps precisely to FDD's "Design by Feature" phase: the Chief Programmer produ 4. **Add "problem context" to the task template.** Distinct from "scope" and "acceptance criteria," problem context explains WHY the acceptance criteria matter, giving the implementing agent enough understanding to exercise judgment when the landscape differs from expectations. -**File:** `skills/issue-craft/SKILL.md` -- regeneration via Issue #9 using the adopted external `skill-creator` workflow. +**File:** `skills/issue-craft/SKILL.md` -- regeneration via Issue #9 using the then-current external authoring workflow. #### No new decomposition skills needed @@ -483,7 +483,7 @@ The composite does not introduce sovereignty violations at the seams because eac | `requesting-code-review` | Verification | Curated | No | | `receiving-code-review` | Verification | Curated | No | | `verification-before-completion` | Verification | Curated | No | -| `writing-skills` | Meta (historical) | Removed | N/A -- superseded by external `skill-creator` for authoring | +| `writing-skills` | Meta (historical) | Removed | N/A -- superseded by an external authoring workflow | ### 4.3 Meta Skills @@ -510,7 +510,7 @@ All other curated skills (TDD, debugging, subagent orchestration, code review, v Ordered by dependency and leverage: -1. **Regenerate `issue-craft`** (Issue #9) -- Add `decompose-design` procedure, refocus on problem transfer, strengthen anti-prescription guardrails. Use the adopted external `skill-creator` workflow. +1. **Regenerate `issue-craft`** (Issue #9) -- Add `decompose-design` procedure, refocus on problem transfer, strengthen anti-prescription guardrails. Use the then-current external authoring workflow. 2. **Update pipeline documentation** -- Remove `writing-plans` from default flow in WORKFLOW.md, pipeline-contract.md, and `using-groundwork`. Update handoff contracts. Document `plan -> issue-craft` as the canonical decomposition boundary. Override `brainstorming` terminal routing. diff --git a/docs/research/existing-skill-implementations.md b/docs/research/existing-skill-implementations.md index 5321de4..7667544 100644 --- a/docs/research/existing-skill-implementations.md +++ b/docs/research/existing-skill-implementations.md @@ -56,7 +56,7 @@ relative to Groundwork's methodology: | Superpowers Skill | What It Does | What to Learn | |---|---|---| | **brainstorming** | Socratic design refinement: one-question-at-a-time dialogue, 2-3 approaches with tradeoffs, design doc before any implementation. | The hard gate on implementation ("Do NOT invoke any implementation skill... until you have presented a design and the user has approved it") is a strong pattern. Our `ground` skill could reference this approach for design phases. | -| **writing-skills** (meta-skill) | TDD applied to skill creation: RED-GREEN-REFACTOR cycle using pressure scenarios on subagents. Includes Cialdini's persuasion principles adapted for LLM compliance. | Historical research input only. The pressure-testing methodology remains valuable, but Groundwork later adopted external `skill-creator` for live skill authoring instead of curating `writing-skills` into the runtime pipeline. | +| **writing-skills** (meta-skill) | TDD applied to skill creation: RED-GREEN-REFACTOR cycle using pressure scenarios on subagents. Includes Cialdini's persuasion principles adapted for LLM compliance. | Historical research input only. The pressure-testing methodology remains valuable, but Groundwork later used an external authoring workflow instead of curating `writing-skills` into the runtime pipeline. | | **writing-plans** | Converts designs into bite-sized tasks (2-5 min, exact file paths, complete code). | The granularity model (2-5 min tasks with exact code) is useful for understanding how our issue-level decomposition hands off to task-level decomposition. | | **requesting-code-review** / **receiving-code-review** | Dispatches code-reviewer subagent; handles review feedback with explicit ban on performative agreement ("You're absolutely right!" is forbidden). | The anti-performative-agreement stance and the push-back-when-wrong protocol are worth incorporating into any Groundwork verification skill. | diff --git a/docs/research/what-should-groundwork-be-made-of.md b/docs/research/what-should-groundwork-be-made-of.md index 9ab8851..a277b76 100644 --- a/docs/research/what-should-groundwork-be-made-of.md +++ b/docs/research/what-should-groundwork-be-made-of.md @@ -190,7 +190,7 @@ Recommendation: learn from, or adapt into a lightweight "change threat check" ga Solves: "skills that don't actually change behavior" by applying TDD-style RED/GREEN/REFACTOR to process docs. Quality: excellent and aligned with Groundwork's mission. Mission fit: high (Groundwork is a methodology library). -Recommendation: historical candidate only. Groundwork later adopted external `skill-creator` as the contributor-facing skill-authoring system instead of adding `writing-skills` to the runtime library. +Recommendation: historical candidate only. Groundwork later used an external authoring workflow instead of adding `writing-skills` to the runtime library. ---