docs: polish README and add contributor scaffolding

.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.

.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.

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.

README.md

@@ -6,6 +6,7 @@
   <a href="https://github.com/Obsidian-Owl/specwright/releases"><img src="https://img.shields.io/github/v/release/Obsidian-Owl/specwright?style=flat-square&color=f59e0b&label=version" alt="Version"></a>
   <a href="LICENSE"><img src="https://img.shields.io/github/license/Obsidian-Owl/specwright?style=flat-square&color=475569" alt="License"></a>
   <a href="https://github.com/Obsidian-Owl/specwright/stargazers"><img src="https://img.shields.io/github/stars/Obsidian-Owl/specwright?style=flat-square&color=475569" alt="Stars"></a>
+  <a href="https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/plugins"><img src="https://img.shields.io/badge/Made_for-Claude_Code-cc785c?style=flat-square" alt="Made for Claude Code"></a>
 </p>
 
 <p align="center">
@@ -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.
 
 ---
 
+<p align="center">
+  If Specwright helps you ship with confidence, <a href="https://github.com/Obsidian-Owl/specwright">a ⭐ helps others find it</a>.
+</p>
+
 <p align="center">
   <sub>Built by <a href="https://github.com/Obsidian-Owl">ObsidianOwl</a> · MIT License · v0.7.0</sub>
 </p>