Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
50 changes: 28 additions & 22 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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-name>/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

Expand Down
74 changes: 0 additions & 74 deletions docs/architecture/decisions/0004-skill-authoring-system.md

This file was deleted.

6 changes: 3 additions & 3 deletions docs/research/epic-7-methodology-research.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand All @@ -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.

Expand Down
2 changes: 1 addition & 1 deletion docs/research/existing-skill-implementations.md
Original file line number Diff line number Diff line change
Expand Up @@ -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. |

Expand Down
2 changes: 1 addition & 1 deletion docs/research/what-should-groundwork-be-made-of.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

---

Expand Down