From 1e33731daa6dcff579d923811938ce87d708004f Mon Sep 17 00:00:00 2001 From: MacAttak Date: Mon, 16 Feb 2026 14:56:58 +1100 Subject: [PATCH] docs: polish README and add contributor scaffolding Add "Made for Claude Code" badge, "Why Specwright?" section with pain-point summary, comparison table vs other tools, and star CTA. Create CONTRIBUTING.md with development setup and architecture overview. Add bug report and feature request issue templates. Co-Authored-By: Claude Opus 4.6 --- .github/ISSUE_TEMPLATE/bug_report.md | 37 ++++++++++++ .github/ISSUE_TEMPLATE/feature_request.md | 23 ++++++++ CONTRIBUTING.md | 72 +++++++++++++++++++++++ README.md | 26 +++++++- 4 files changed, 157 insertions(+), 1 deletion(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 CONTRIBUTING.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..d6e2f59 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,37 @@ +--- +name: Bug Report +about: Report a problem with Specwright +title: "[Bug] " +labels: bug +assignees: '' +--- + +## Environment + +- **Claude Code version:** (`claude --version`) +- **Specwright version:** (e.g. v0.7.0) +- **OS:** (e.g. macOS 15, Ubuntu 24.04) +- **Skill affected:** (e.g. `/sw-verify`, `/sw-build`) + +## What happened? + +A clear description of the bug. + +## Steps to reproduce + +1. Run `/sw-init` on a project +2. Run `/sw-design ...` +3. ... +4. See error + +## Expected behaviour + +What you expected to happen. + +## Actual behaviour + +What actually happened. Include error messages or screenshots if available. + +## Additional context + +Any other details — project type, configuration, related issues. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..842e4cd --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,23 @@ +--- +name: Feature Request +about: Suggest a new feature or improvement +title: "[Feature] " +labels: enhancement +assignees: '' +--- + +## Use case + +What problem are you trying to solve? Describe the situation where this feature would help. + +## Proposed solution + +How do you think this should work? Describe the ideal behaviour. + +## Alternatives considered + +Have you tried any workarounds or considered other approaches? + +## Additional context + +Any other details — examples from other tools, mockups, related issues. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..cd9ddec --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,72 @@ +# Contributing to Specwright + +Thanks for your interest in contributing! Specwright is an open-source Claude Code plugin and we welcome bug reports, feature suggestions, and pull requests. + +## Reporting Bugs + +Open a [bug report issue](https://github.com/Obsidian-Owl/specwright/issues/new?template=bug_report.md) with: + +- Your Claude Code version (`claude --version`) +- Specwright version (check `skills/sw-init/SKILL.md` frontmatter or the latest release) +- Steps to reproduce the problem +- What you expected vs what happened +- Any error output or screenshots + +## Suggesting Features + +Open a [feature request issue](https://github.com/Obsidian-Owl/specwright/issues/new?template=feature_request.md) describing: + +- The use case or problem you're solving +- Your proposed solution +- Alternatives you've considered + +## Submitting Pull Requests + +1. Fork the repo and create a feature branch from `main` +2. Make your changes (see Architecture below for orientation) +3. Test your changes by running the affected skills in a real project +4. Submit a PR with a clear description of what changed and why + +### Commit Conventions + +Use [Conventional Commits](https://www.conventionalcommits.org/): + +- `feat:` new functionality +- `fix:` bug fixes +- `docs:` documentation changes +- `refactor:` code restructuring without behaviour change +- `chore:` maintenance tasks + +## Architecture Overview + +``` +specwright/ +├── skills/ # 15 SKILL.md files (10 user-facing + 5 internal gates) +├── protocols/ # 12 shared protocols (loaded on demand by skills) +├── agents/ # 6 custom subagent definitions +├── hooks/ # Session lifecycle hooks +├── CLAUDE.md # Project instructions for Claude Code +├── DESIGN.md # Full architecture document +└── README.md +``` + +**Skills** define *what* to achieve (goals + constraints), not step-by-step procedures. Each stays under 600 tokens. + +**Protocols** extract fragile operations (git, state, recovery) into shared documents loaded on demand. Skills reference them but don't inline their content. + +**Agents** are custom subagent definitions with specific roles (architect, tester, executor, reviewer, build-fixer, researcher). + +For the full architecture, see [`DESIGN.md`](DESIGN.md). For development guidelines and key rules, see [`CLAUDE.md`](CLAUDE.md). + +## Development Setup + +Specwright is a Claude Code plugin — it's a collection of skill, protocol, and agent definitions (Markdown files), not a compiled application. To develop: + +1. Clone the repo +2. Install the plugin locally: `/plugin install /path/to/specwright` +3. Test skills by running them in a real or test project +4. Check that modified skills stay under the 600-token target + +## Code of Conduct + +Be respectful and constructive. We're all here to build better tools. diff --git a/README.md b/README.md index fe6f161..4e8af91 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,7 @@ Version License Stars + Made for Claude Code

@@ -14,7 +15,9 @@ --- -Most spec-driven frameworks help you plan. Then they leave you on your own. +## Why Specwright? + +AI agents optimise for "done." That's the problem. Code compiles, tests pass, CI is green — and three days later you find an export nobody imports, a handler that's never called, a validation rule that exists in the spec but not in the code. **The hard part isn't writing code. It's proving it works.** Specwright closes the **entire loop** — design, plan, build, verify, ship, learn. Every requirement is tracked to implementation evidence. Every PR ships with proof, not promises. @@ -38,6 +41,23 @@ Specwright closes the **entire loop** — design, plan, build, verify, ship, lea - Periodic health checks find systemic debt that per-change gates miss - One install, configure once, works with any language or framework +### How It Compares + +| Capability | Specwright | [Spec Kit](https://github.com/spec-kit/spec-kit) | [Oh-My-ClaudeCode](https://github.com/anthropics/oh-my-claudecode) | Manual workflows | +|---|---|---|---|---| +| Structured spec writing | Yes | **Yes** — core strength | Partial | DIY | +| Adversarial TDD (separate tester/executor) | **Yes** | No | No | No | +| Wiring verification (orphaned code, layer violations) | **Yes** | No | No | No | +| Evidence-based PRs (criterion → code + test) | **Yes** | No | No | No | +| Quality gates with findings (not just badges) | **Yes** | No | Partial | DIY | +| Compaction recovery | **Yes** | No | No | No | +| Learning system (patterns promoted across sessions) | **Yes** | No | No | No | +| Codebase knowledge persistence | **Yes** | No | No | No | +| Configurability / extensibility | Moderate | Moderate | **High** — core strength | Full control | +| Lightweight / low ceremony | No — opinionated by design | **Yes** | **Yes** | Varies | + +Every tool in this space pushes AI-assisted development forward. Specwright's focus is the **verification and evidence gap** — the part between "tests pass" and "it actually works." + ## What Makes This Different Other tools in this space focus on the **specification phase** — they help you write a plan, then hand off to the AI. The hard part isn't planning. It's everything after: does the code actually do what was asked? Is it wired up? Is it secure? Can you prove it? @@ -256,6 +276,10 @@ Specwright is open source under the MIT license. --- +

+ If Specwright helps you ship with confidence, a ⭐ helps others find it. +

+

Built by ObsidianOwl · MIT License · v0.7.0