osapi-io · retr0h · Mar 3, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,63 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with
+code in this repository.
+
+## Project Overview
+
+[Remote Taskfile](https://taskfile.dev/experiments/remote-taskfiles/)s used by
+[osapi-io](https://github.com/osapi-io) projects. Provides shared Go, BATS,
+and Docusaurus task definitions that consuming projects include via URL.
+
+## Development Reference
+
+- @docs/development.md - Prerequisites, setup, conventions, commits
+- @docs/contributing.md - PR workflow and contribution guidelines
+
+## Quick Reference
+
+```bash
+task go:test        # Run all Go checks
+task go:unit        # Run unit tests only
+task bats:test      # Run BATS tests
+```
+
+## Repository Structure
+
+- `go.yml` - Go build, test, lint, and formatting tasks
+- `bats.yml` - BATS integration test tasks
+- `docs.yml` - Docusaurus documentation tasks
+
+## Code Standards (MANDATORY)
+
+### Taskfile Style
+
+- Use `desc:` on every public task
+- Use colon-separated namespacing for sub-tasks (e.g., `fmt:check`)
+- Keep tasks independently runnable where possible
+- Chain checks in `test` task (mod, fmt, vet, coverage)
+
+### Parity with Justfiles
+
+These taskfiles mirror `osapi-justfiles/`. When updating tasks here, consider
+whether the corresponding justfile needs the same change.
+
+### Branching
+
+When committing changes via `/commit`, create a feature branch first if
+currently on `main`. Branch names use the pattern `type/short-description`
+(e.g., `feat/add-docs-task`, `fix/coverage-path`, `chore/update-deps`).
+
+### Task Tracking
+
+Implementation planning and execution uses the superpowers plugin workflows
+(`writing-plans` and `executing-plans`). Plans live in `docs/plans/`.
+
+### Commit Messages
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/) with the
+50/72 rule. Format: `type(scope): description`.
+
+When committing via Claude Code, end with:
+- `🤖 Generated with [Claude Code](https://claude.ai/code)`
+- `Co-Authored-By: Claude <noreply@anthropic.com>`
diff --git a/README.md b/README.md
@@ -1,18 +1,73 @@
+[![license](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=for-the-badge)](LICENSE)
+[![conventional commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg?style=for-the-badge)](https://conventionalcommits.org)
+![gitHub commit activity](https://img.shields.io/github/commit-activity/m/osapi-io/osapi-io-taskfiles?style=for-the-badge)
+
 # Remote Taskfiles
 
 [Remote Taskfile][]s used by [osapi-io][] projects.
 
-## Usage
+## 📦 Usage
 
 ```yaml
 version: '3'
 
 includes:
-  go: https://raw.githubusercontent.com/osapi-io/osapi-io-taskfile/refs/heads/main/go.yml
-  bats: https://raw.githubusercontent.com/osapi-io/osapi-io-taskfile/refs/heads/main/bats.yml
+  go: https://raw.githubusercontent.com/osapi-io/osapi-io-taskfiles/refs/heads/main/go.yml
+  bats: https://raw.githubusercontent.com/osapi-io/osapi-io-taskfiles/refs/heads/main/bats.yml
+  docs: https://raw.githubusercontent.com/osapi-io/osapi-io-taskfiles/refs/heads/main/docs.yml
 ```
 
-## License
+## ✨ Available Taskfiles
+
+### go.yml
+
+| Task          | Description                                       |
+| ------------- | ------------------------------------------------- |
+| `deps`        | Install Go tool dependencies                      |
+| `mod`         | Module maintenance (download + tidy)              |
+| `vet`         | Run golangci-lint                                 |
+| `run`         | Compile and run Go program                        |
+| `unit`        | Run unit tests                                    |
+| `unit:int`    | Run integration tests (requires running service)  |
+| `unit:cov`    | Run tests with coverage                           |
+| `test`        | Run all checks (mod, fmt, vet, coverage)          |
+| `fmt`         | Auto-format with gofumpt + golines               |
+| `fmt:check`   | Check formatting                                  |
+| `generate`    | Run go generate                                   |
+| `docs`        | Generate Go package docs with gomarkdoc           |
+| `docs:check`  | Verify generated docs are up to date              |
+
+### bats.yml
+
+| Task         | Description                     |
+| ------------ | ------------------------------- |
+| `deps`       | Install BATS and shfmt          |
+| `fmt`        | Format .bats files              |
+| `fmt:check`  | Check .bats formatting          |
+| `test`       | Run BATS integration tests      |
+
+### docs.yml
+
+| Task           | Description                    |
+| -------------- | ------------------------------ |
+| `deps`         | Install global dependencies    |
+| `build`        | Build documentation site       |
+| `start`        | Start dev server               |
+| `serve`        | Preview built site             |
+| `clean`        | Clean build directory          |
+| `bump`         | Create new docs version        |
+| `deploy`       | Build and deploy               |
+| `fmt`          | Format docs with prettier      |
+| `fmt:check`    | Check docs formatting          |
+| `generate`     | Generate OpenAPI docs          |
+
+## 🤝 Contributing
+
+See the [Development](docs/development.md) guide for prerequisites, setup,
+and conventions. See the [Contributing](docs/contributing.md) guide before
+submitting a PR.
+
+## 📄 License
 
 The [MIT][] License.
 

diff --git a/docs/contributing.md b/docs/contributing.md
@@ -0,0 +1,49 @@
+# Contributing
+
+Contributions to osapi-io-taskfiles are very welcome, but we ask that you read
+this document before submitting a PR.
+
+## Before you start
+
+- Read the [Development](development.md) guide for prerequisites, setup, and
+  commit message conventions.
+- **Check existing work** — Is there an existing PR? Are there issues discussing
+  the feature/change you want to make? Please make sure you consider/address
+  these discussions in your work.
+- **Backwards compatibility** — Will your change break existing consumers of
+  osapi-io-taskfiles? It is much more likely that your change will be merged if
+  it is backwards compatible. Is there an approach you can take that maintains
+  this compatibility? If not, consider opening an issue first so that changes can
+  be discussed before you invest your time into a PR.
+
+## Making changes
+
+- **Documentation** — Ensure that you add/update any relevant documentation.
+- **Testing** — Test your changes against a consuming project before submitting.
+
+## Submitting a PR
+
+- **Describe your changes** — Ensure that you provide a comprehensive
+  description of your changes.
+- **Issue/PR links** — Link any previous work such as related issues or PRs.
+  Please describe how your changes differ to/extend this work.
+- **Examples** — Add any examples or screenshots that you think are useful to
+  demonstrate the effect of your changes.
+- **Draft PRs** — If your changes are incomplete, but you would like to discuss
+  them, open the PR as a draft and add a comment to start a discussion. Using
+  comments rather than the PR description allows the description to be updated
+  later while preserving any discussions.
+
+## FAQ
+
+> I want to contribute, where do I start?
+
+All kinds of contributions are welcome, whether it's a typo fix or a shiny new
+task. You can also contribute by upvoting/commenting on issues or helping to
+answer questions.
+
+> I'm stuck, where can I get help?
+
+If you have questions, feel free to open a [Discussion][] on GitHub.
+
+[Discussion]: https://github.com/osapi-io/osapi-io-taskfiles/discussions
diff --git a/docs/development.md b/docs/development.md
@@ -0,0 +1,65 @@
+# Development
+
+This guide covers the tools, setup, and conventions needed to work on
+osapi-io-taskfiles.
+
+## Prerequisites
+
+- **[Task][]** — Task runner used by consuming projects. Install with
+  `brew install go-task`.
+
+### Claude Code
+
+If you use [Claude Code][] for development, install these plugins from the
+default marketplace:
+
+```
+/plugin install commit-commands@claude-plugins-official
+/plugin install superpowers@claude-plugins-official
+```
+
+- **commit-commands** — provides `/commit` and `/commit-push-pr` slash commands
+  that follow the project's commit conventions automatically.
+- **superpowers** — provides structured workflows for planning, TDD, debugging,
+  code review, and git worktree isolation.
+
+## Making Changes
+
+Edit the YAML taskfiles directly. To test changes, point a consuming project's
+`Taskfile.yml` at your local branch:
+
+```yaml
+includes:
+  go: https://raw.githubusercontent.com/osapi-io/osapi-io-taskfiles/refs/heads/your-branch/go.yml
+```
+
+## Branching
+
+All changes should be developed on feature branches. Create a branch from `main`
+using the naming convention `type/short-description`, where `type` matches the
+[Conventional Commits][] type:
+
+- `feat/add-docs-task`
+- `fix/coverage-path`
+- `chore/update-deps`
+
+When using Claude Code's `/commit` command, a branch will be created
+automatically if you are on `main`.
+
+## Commit messages
+
+Follow [Conventional Commits][] with the 50/72 rule:
+
+- **Subject line**: max 50 characters, imperative mood, capitalized, no period
+- **Body**: wrap at 72 characters, separated from subject by a blank line
+- **Format**: `type(scope): description`
+- **Types**: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`
+- Summarize the "what" and "why", not the "how"
+
+Try to write meaningful commit messages and avoid having too many commits on a
+PR. Most PRs should likely have a single commit (although for bigger PRs it may
+be reasonable to split it in a few). Git squash and rebase is your friend!
+
+[Task]: https://taskfile.dev
+[Claude Code]: https://claude.ai/code
+[Conventional Commits]: https://www.conventionalcommits.org