Skip to content

contributing

Jump to bottom
github-actions[bot] edited this page Jul 4, 2026 · 1 revision

"Contributing" means two different things here, and it's worth keeping them apart:

This page (SpecUI project) Your app with .specui/
Goal Improve @logicplanes/specui on GitHub Onboard teammates to your design contract
Docs Edit wiki/*.md here Your README + .specui/ + AGENTS.md

Contribute to SpecUI (open source)

Issues and pull requests are welcome on logicplanes/specui.

Before you open a PR

  1. Read the repo's CONTRIBUTING.md and AGENTS.md (maintainer/agent rules for this repo).
  2. Run the tests:
npm test
npm run verify:repo-setup
npm run check:docs-sync
  1. User-facing docs: edit files in wiki/ only — site/content/docs/*.mdx is generated, and edits there will be overwritten. Then:
npm run sync:docs
  1. For user-facing product changes, update changelog.json → unreleased.

Branches

  • Day-to-day work happens on dev
  • Production docs site + releases come from prod

Maintainers: see docs/RELEASING.md.

Report bugs

  • Bug report template
  • Include: specui --version and specui validate .specui --json output (redact secrets)

Ideas

Document your own SpecUI consumer project

Recommendations for your product repo:

  1. README — link to the SpecUI docs, show init + validate --strict
  2. AGENTS.md — keep the SpecUI block current (specui init --agents-md)
  3. .specui/AGENTS-GUIDE.md — ships with init; point new agents there
  4. CI — npx specui validate .specui --strict on every PR (CI/CD)
  5. CONTRIBUTING.md (your app) — one line goes a long way: "UI changes must update .specui/ in the same PR"

You don't need to fork the SpecUI wiki for app docs — link to this site for CLI reference.

Edit the public docs site

Step Action
1 Change wiki/<page>.md
2 Update wiki/meta.json if adding/removing pages
3 npm run sync:docs
4 cd site && npm run build
5 PR to dev; the site publishes from prod

The Wiki on GitHub is synced separately via a project workflow (see the repo's sync-wiki).

Coding agents (this repo)

Maintainers use the repo's own AGENTS.md — not the same thing as the consumer AGENTS.md block your app gets from specui init.

Next steps

Getting started

How-to guides

Reference

Community

Clone this wiki locally