Skip to content

derdavidbohl/good-practice-harness

v1.0.0

A set of Copilot skills for capturing, documenting, and implementing repository context.

Good Practice Harness

Good Practice Harness is a GitHub Copilot CLI Agent Plugin that provides a structured workflow for turning a repository into a spec-driven repository before implementing changes. The context is the normative specification, and repository content must be based on that context.

Skills

The plugin includes these skills:

SkillPurpose
get-contextFind and read the current repository context.
onboard-repositoryBuild context and identify or create repository-specific verification checks.
context-requirementsCapture stakeholders and non-technical requirements.
context-architectureIdentify and document architecture and decisions.
context-codingDefine coding standards and practices.
context-qualityDefine quality goals and guide agent-led, repository-specific verification.
context-securityIdentify security concerns, assets, and mitigations.
context-user-experienceCapture user experience flows and expectations.
document-contextKeep context documentation structured and consistent.
maintain-contextReview and update repository context specifications for completeness, consistency, and traceability.
make-changeImplement requested changes using the documented repository context.
workflowCoordinate the preferred workflow for repository requests.

Install

Install directly from a local checkout while developing the plugin:

copilot plugin install /path/to/good-practice-harness

After installation, start a new Copilot CLI session or restart the current session to load the skills.

Use

For a repository without /context, start by onboarding:

Use the onboard-repository skill to document this repository.

For ordinary repository requests, use the workflow orchestrator:

Use the workflow skill to fix the validation error in the configuration parser.

To review or maintain repository context:

Use the maintain-context skill to review and update this repository's context.

workflow reads the relevant repository context, asks only for blocking clarifications, and coordinates implementation and verification through make-change. Focused skills can also be invoked directly for scoped context work. If onboarding is declined or no relevant context exists, implementation does not proceed until that context is established. After onboarding, every implementation change must be preceded by an update to the relevant context specification, even when the general behavior is already documented. Context updates capture intent and acceptance needs, not implementation details. Context-neutral changes, which preserve everything the context specifies (for example dependency updates without behavior change, refactoring, or formatting), are exempt; the change summary states why.

Plugin layout

Agent Plugins 1.0 discovers skills from immediate subdirectories of skills/ containing a SKILL.md file. The manifest is at the repository root:

plugin.json
README.md
skills/
  context-architecture/SKILL.md
  context-coding/SKILL.md
  ...

Development

Keep skill names lowercase and hyphenated, and keep the name and description frontmatter fields synchronized with the directory's purpose. Run the harness checks after changes (requires jq):

jq empty plugin.json
bash skills/document-context/scripts/test_harness.sh

License

This project is licensed under the MIT License. See LICENSE for the full text.