# Contributing to Taskrail

Humans and AI agents both contribute here. This is the fast path plus the
human-facing rules. For depth:

- **Coding agents / AI tools:** [`AGENTS.md`](AGENTS.md) is authoritative — read it first.
- **Full process:** [`docs/workflow/`](docs/workflow/).
- **Product scope:** the versioned specs under [`specs/`](specs/).

## AI-assisted contributions

AI-generated and AI-assisted PRs are welcome — Taskrail is built that way. Two rules:

1. **You own the diff.** Whoever opens the PR is accountable for every line,
   AI-written or not. "The model wrote it" is not a review exemption.
2. **No bot attribution.** Do not add `Co-Authored-By: <bot>` or `Generated
   with …` trailers. The `commit-msg` hook rejects them. Your name on the
   commit; the AI is your tool, not a co-author.

The same quality gate applies regardless of how the code was produced.

## Setup

See [README → Development](README.md#development). Fastest path:

```sh
git clone https://github.com/tessariq/taskrail.git
cd taskrail
mise run setup    # toolchain + opt-in git hooks (recommended)
```

Direct `go` commands work without mise.

## Before you open a PR

- `gofmt -w` on changed Go files; `go vet ./...`; `go test ./...` — all green.
- `taskrail validate` if you touched `planning/`, `specs/`, or the task/state schema.
- Conventional Commit subject with only the short task key as a suffix:
  `feat: add repair surface (T-050)` — never the full slugged task identifier or
  a task prefix.
- After the subject and a blank line, include a concise body explaining the
  commit's intent, context, and non-obvious decisions rather than restating the
  diff. Wrap body lines at 72 characters. The `commit-msg` hook requires this
  body and line limit for ordinary commits.
- Update `CHANGELOG.md` under `## Unreleased` for user-visible changes only.
  Keep it terse: one to two lines, lead with the command. Skip internal refactors.
  Policy and examples: [`docs/workflow/changelog.md`](docs/workflow/changelog.md).
- No bot-attribution trailers (see above).

## Tracked work and STATE.md

`planning/STATE.md` is generated by the CLI. **Never hand-edit it.** Route status
changes through `taskrail start|complete|block|verify`. In this source checkout,
run `task taskrail:check` immediately before each such bare `taskrail` writer and
stop if it fails; `go run ./cmd/taskrail ...` builds current source and needs no
guard. Commit the regenerated `STATE.md` (and any rewritten task files) in the
*same* commit as the change that produced them. Run `git status` after any CLI
transition. Details in [`AGENTS.md`](AGENTS.md).

## Scope

Keep PRs focused on one logical outcome. **Ask first** before: changing the task
or state schema, spec contracts, or CI checks; adding a runtime dependency (prefer
the standard library); or broad refactors beyond a task's scope. Taskrail stays a
repo-local CLI — not a sandbox, container orchestrator, or background daemon.

## License

By contributing you agree that your contributions are licensed under Apache-2.0
(see [LICENSE](LICENSE)).