{"id":51162468,"url":"https://github.com/ribeirogab/specwright","last_synced_at":"2026-06-26T15:02:17.267Z","repository":{"id":355079655,"uuid":"1225944065","full_name":"ribeirogab/specwright","owner":"ribeirogab","description":"Spec-driven workflow for AI coding agents.","archived":false,"fork":false,"pushed_at":"2026-06-25T15:34:32.000Z","size":1040,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-25T17:17:07.143Z","etag":null,"topics":["agent-skills","agents-md","ai-agents","claude-code","harness","harness-engineering","harness-framework","spec-driven-development"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ribeirogab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE.md","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-30T20:10:14.000Z","updated_at":"2026-06-25T15:34:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ribeirogab/specwright","commit_stats":null,"previous_names":["ribeirogab/agent-skills","ribeirogab/memex","ribeirogab/specwright"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ribeirogab/specwright","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ribeirogab%2Fspecwright","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ribeirogab%2Fspecwright/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ribeirogab%2Fspecwright/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ribeirogab%2Fspecwright/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ribeirogab","download_url":"https://codeload.github.com/ribeirogab/specwright/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ribeirogab%2Fspecwright/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34821764,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-26T02:00:06.560Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","agents-md","ai-agents","claude-code","harness","harness-engineering","harness-framework","spec-driven-development"],"created_at":"2026-06-26T15:02:10.684Z","updated_at":"2026-06-26T15:02:17.261Z","avatar_url":"https://github.com/ribeirogab.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# specwright\n\n`specwright` gives any repository an explicit **spec-driven workflow** — every non-trivial change runs through one pipeline: brainstorm → design → spec + tasks → implement → quality gate → PR → review-to-`lgtm`. Agent-agnostic and self-hosting.\n\n---\n\n## Install\n\nFrom your project root:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/ribeirogab/specwright/main/install.sh | sh\n```\n\nThis:\n\n- installs the scaffolder skill — `.agents/skills/sw/`, plus the `.claude/skills/sw` symlink, and\n- enables the `sw` plugin in `.claude/settings.json`.\n\nThen open the repo in your agent and run `/sw` to audit and scaffold the `.specwright/` vault. The plugin commands (`/sw:spec`, `/sw:new-pr`, …) load once Claude Code trusts the workspace.\n\n## Use\n\nPoint an agent at any repo where you want specwright installed:\n\n\u003e \"Audit specwright in this repo and scaffold whatever is missing.\"\n\nThe skill is audit-first, autonomous-fix, and safe to re-run. After the first run the repo has a working `.specwright/` vault, the bundled `sw-*` companion skills, the `/sw:*` slash commands, and an `AGENTS.md` — all dogfood-tested by specwright's own validator.\n\n**Source:** [`skills/sw/SKILL.md`](skills/sw/SKILL.md)\n\n## What you get\n\nAfter install the repo has:\n\n- an **`AGENTS.md`** describing the spec-driven workflow,\n- a **`.specwright/` vault** holding just `conventions/` (project-specific conventions) and `specs/` (dated spec folders), and\n- a set of **`/sw:*` commands** and companion skills:\n\n| Command | What it does |\n|---|---|\n| `/sw` | Scaffold or audit specwright in the current repo — set up, verify, or fix. Idempotent. |\n| `/sw:brainstorming` | Explore intent and design before any non-trivial change → `design.md`. |\n| `/sw:spec` | Turn the current conversation into a spec and enter the flow. |\n| `/sw:writing-plans` | Turn an approved design into the technical `spec.md` + `tasks.md`. |\n| `/sw:review-spec` | External-evaluator pass over a spec — flags vagueness, scope creep, design drift. |\n| `/sw:new-pr` | Open the spec's PR — branch/base, push, PR template, Conventional-Commit title. |\n| `/sw:code-review` | Review the branch diff with find-only subagents until `lgtm`. |\n| `/sw:update` | Sync the installed specwright with upstream without clobbering local edits. |\n\n## How the flow works\n\nEvery non-trivial change runs through one pipeline. **Design approval is the only human review** — everything after it can run on its own.\n\n```mermaid\nflowchart TD\n    A([sw-brainstorming: explore + design → design.md]) --\u003e B{Design approved?}\n    B -- \"no, revise\" --\u003e A\n    B -- yes --\u003e C[\"Post-design batch:\u003cbr/\u003ebranch + mode + worktree + handoff?\"]\n    C --\u003e D[Create branch]\n    D --\u003e E[\"sw-writing-plans: spec + tasks\u003cbr/\u003ethen self-reviews the spec\u003cbr/\u003espec-document-reviewer + sw:review-spec + validate-spec.sh\u003cbr/\u003eboth modes — no human spec review\"]\n    E --\u003e G{handoff?}\n    G -- yes --\u003e H[\"Print txt handoff, then stop\u003cbr/\u003eyou /compact or open a new chat, paste, resume\"]\n    G -- no --\u003e K[Implement]\n    H --\u003e K\n    K --\u003e L[Quality gate]\n    L --\u003e N{mode = autonomous?}\n    N -- yes --\u003e O[\"Deliver: sw:new-pr + sw:code-review to lgtm → shipped\"]\n    N -- \"no (reviewed)\" --\u003e P{Open the PR and run code-review?}\n    P -- yes --\u003e O\n```\n\nA few things worth knowing:\n\n- **One human gate.** You approve the design — nothing else. The agent reviews its *own* spec (the spec-document-reviewer subagent + `/sw:review-spec` + the `validate-spec.sh` mechanical gate), in both modes.\n- **The post-design batch.** Right after design approval, one batch asks four things: the **branch name**, the **mode**, whether to use a **worktree**, and whether to **hand off**.\n- **Two modes.** The mode decides only the **delivery**: `autonomous` opens the PR and runs code-review to `lgtm` on its own; `reviewed` does the same but asks first (*\"open the PR and run code-review?\"*). It is recorded in the spec and counts as consent to commit/push that feature branch.\n- **Worktree.** A specwright-native checkout under `.specwright/worktrees/` — default yes, unless you're already inside a linked worktree.\n- **Handoff (either mode).** Once design/spec/tasks are written, the agent prints a handoff prompt so you can `/compact` (or open a new chat) and implement with a clean context.\n\n## Customizing\n\nThe workflow ships with opinionated defaults — all plain markdown, so change them to fit your team.\n\nCompanion skills live in **three kept-in-sync copies**:\n\n- `.agents/skills/sw-\u003cname\u003e/` — canonical, what non-Claude agents read,\n- `plugins/sw/skills/\u003cname\u003e/` — the Claude Code plugin copy,\n- `skills/sw/scaffold/skills/sw-\u003cname\u003e/` — what new installs receive.\n\nEdit the copy your agent loads. To change what **future** installs get, edit the `scaffold/` copy too — and keep the three in sync.\n\n- **PR conventions (`/sw:new-pr`)** — title/body format, the draft-vs-ready choice, labels, the PR-template fill, push behavior all live in the `sw-new-pr` `SKILL.md`. Edit it to change how PRs are opened (e.g. write the body in another language, change the default base branch, or add labels).\n- **Code-review rules (`/sw:code-review`)** — there are two levers. (1) **Project conventions** the reviewer reads: your installed repo's `.specwright/conventions/` — edit those to change the project-specific standard. (2) **The universal rubric** — the embedded rubric and severity classes (`blocker`/`suggestion`/`nitpick`/`question`), the blocker calibration, and the output format — live in the `sw-code-review` `SKILL.md` (Unix philosophy + meaningful comments + security are baked into code-review now).\n- **The spec-flow steps** — the flow is documented in `AGENTS.md` under `### Spec flow`. To change the steps for an already-installed repo, edit that block; to change what new installs get, edit `### Spec flow` in `skills/sw/references/agents-md-template.md` (keep the two consistent). The `autonomous`/`reviewed` switch is wired across the three `sw-brainstorming` `SKILL.md` copies and the spec template's `branch:`/`mode:` fields, so deeper changes to mode behavior touch those too.\n\n## Repository layout\n\n```\nspecwright/\n├── skills/sw/               # the scaffolder skill: SKILL.md, references/, scaffold/, scripts/\n├── plugins/sw/              # Claude Code plugin — /sw:* commands (commands/) + companion skills (skills/)\n├── .claude-plugin/          # marketplace manifest\n├── LICENSE                  # MIT\n├── NOTICE.md                # attribution for vendored validator scripts\n├── CONTRIBUTING.md\n├── CODE_OF_CONDUCT.md\n├── SECURITY.md\n└── README.md\n```\n\nThe repository also contains `.agents/`, `.claude/`, and `.specwright/` — local dirs used to dogfood specwright on its own development (the bundled companion skills, the per-agent symlinks, and the maintainer's spec vault). They are not what the installer puts in your repo.\n\n## License\n\nThis repository's original work is licensed under the [MIT License](LICENSE). The vendored validator scripts under `skills/sw/scripts/` are Apache-2.0; see [`NOTICE.md`](NOTICE.md) for attribution.\n\n## Contributing\n\nPull requests welcome — see [`CONTRIBUTING.md`](CONTRIBUTING.md) for scope, the quality bar, and the per-PR checklist. By participating, you agree to the [Code of Conduct](CODE_OF_CONDUCT.md). Security concerns go to [`SECURITY.md`](SECURITY.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fribeirogab%2Fspecwright","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fribeirogab%2Fspecwright","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fribeirogab%2Fspecwright/lists"}