# Agile Workflow — Issues, PRs, Autonomous Merge, Releases, Villages

The unified development process for every Tawa repo. If your Claude Code session
loads `tawa-docs/.claude/rules/tawa-agile-workflow.md`, it will follow this flow
automatically.

## Ground Rules

- **Git host is Forgejo only** — everything lives at `git.tawa.pro`. No GitHub, no
  `mcp__github__*` tools. Git operations go through `mcp__jci-mcp__git_*` or the `git` CLI.
- **Remotes are always HTTPS** (`https://git.insureco.io/org/repo.git`). Never switch to
  SSH to fix auth — run `tawa login --save` to reprovision the Forgejo PAT.
- **`main` is PR-only.** Never commit to `main`; it advances solely through a merged PR —
  one the **agent merges itself** (see Autonomous Merge below).

## Issue-Driven Development (required)

Every feature, bug fix, or non-trivial task **must have a git issue** before code is written.

```
Create issue → branch → implement → PR → self-merge → close via commit message
```

1. Check for an existing issue first (`git_issue_list`); create one if missing (`git_issue_create`).
2. Reference the issue number in the commit: `feat: add tagline to branding (#42)`.
3. Auto-close from the commit body with `fix #N`, `close #N`, or `resolve #N`.

Only truly trivial one-liners are exempt.

## The Feature Loop

1. **Create issue first** — `git_issue_create`
2. **Plan** — `planner` agent breaks down the work
3. **TDD** — `tdd-guide` agent, tests written first (RED → GREEN → refactor, 80%+ coverage)
4. **Branch** — in your own worktree off `origin/main`: `claw/<task>-<shortid>`
5. **Code review** — `code-reviewer` agent after writing code
6. **Commit & push** — explicit paths, reference the issue (`feat: add X (#N)`)
7. **Open PR** — `git_pr_create`
8. **Rebase & verify green** — `git fetch origin && git rebase origin/main`, then run the
   repo's typecheck / lint / tests. This is the gate that replaces human review.
9. **Self-merge** — `git_pr_merge`. Automatic; do not wait for a human (see below).
10. **Cut release** — `git_release_create` after a deploy-worthy batch

## Autonomous Merge — Agents Self-Merge Their PRs

**Every agent runs the full pipeline end-to-end and merges its own PR. The merge is the
default terminal step, not a handoff.** The human ("vibe coder") does not review or click
merge — they tell the agent to *test before merging*, and a green, rebased PR merges
itself. Agents are pulled in **only on a major error**.

**Do NOT wait for the human:**
- Never end a turn at "PR is open, ready for you to merge." A PR you opened is yours to merge.
- Never ask "want me to merge this?" for a routine change — merging is the assumed intent.
- When agents fan out, the orchestrator **serializes** merges (one PR at a time, each
  rebased on the prior merge) and **merges them itself** — nothing is parked for a person.

**Escalate instead of merging — STOP and surface to the human ONLY when:**
- A **merge/rebase conflict** you cannot cleanly and confidently resolve.
- **Typecheck / lint / tests / build fail** and you can't green them.
- A **deploy-gate or smoke-test failure**, or a red post-merge signal.
- The change is **destructive, irreversible, or outside the task's stated scope** (schema
  drops, data migrations, mass deletions, secret rotation, force-push to a protected branch).
- A **security-sensitive** change you're not confident is correct.
- Genuinely **ambiguous requirements** where the wrong guess is expensive.

"I'm slightly unsure the feature is perfect" is **not** a major error — that's what the
issue, the diff, and the next iteration are for. Outside the list above, proceed to merge.

**Permissions & enforcement (already in place):**
- Claude Code's global settings allow `Bash(*)` and the Forgejo PR tools (`git_pr_create`,
  `git_pr_merge`, `git_pr_get`, `git_pr_list`) with no prompt.
- Branch protection (`forgejo-protect-main`, `required_approvals=0`) enforces PR-only
  mechanically while still letting the agent self-merge — that is exactly why approvals are 0.

**Deploy is still a separate, single-owner step.** After the merge(s) land on `origin/main`,
one agent runs `tawa deploy --prod` once. Autonomous merge changes the *merge* gate, not the
*ship* gate. See `deploy-pipeline`.

## Labels — the board's source of truth

**Type labels:** `feature`, `bug`, `ux`, `infra`, `debt`, `phase`

**Status labels → Kanban columns** (moving a card = swap the `status:*` label):

| Label | Column | Color |
|-------|--------|-------|
| `status:backlog` | Backlog | `#64748b` |
| `status:in-progress` | In Progress | `#2563eb` |
| `status:review` | In Review | `#d97706` |
| `status:blocked` | Blocked | `#dc2626` |
| (closed, no label) | Done | automatic |

## Sprint Rhythm

1. **Plan** — review open issues, pick the sprint's work, label with milestone
2. **Build** — one issue per branch/feature, commit often
3. **Ship** — the agent **self-merges its own PR** (rebase → verify green → `git_pr_merge`),
   cuts a release, closes issues. No human merge gate.
4. **Retrospect** — which issues stayed open, and why?

### Commit message format

```
<type>: <description> (#N)
```

Types: `feat, fix, refactor, docs, test, chore, perf, ci`. Always link the issue when one
exists. Attribution is disabled globally.

## Release Management

Cut a release after every meaningful, deployed batch. Check existing releases first
(`git_release_list`), then `git_release_create`.

| Bump | Meaning |
|------|---------|
| Patch `v1.0.x` | Bug fixes, minor tweaks |
| Minor `v1.x.0` | New features, UI additions |
| Major `vX.0.0` | Breaking changes, rewrites |

## Documentation & Decisions

Use the **wiki** to capture the *why* — architecture decisions, non-obvious "why X instead
of Y" choices, onboarding context (data model, auth flow, deploy process). Tools:
`git_wiki_create` / `git_wiki_update`. Write a wiki page when a new pattern is introduced or
a non-obvious decision is made; update it when behavior changes.

## Villages — Cross-Repo System Tracking

The ecosystem is organized into **Villages** — high-level system components spanning multiple
repos. All 15 Villages reaching v1 constitutes **Voyager** (Ecosystem Release 1).

- Issues live in the repo where the code lives; a **Forgejo org-level Project** (one per
  Village) is the cross-repo board.
- Each constituent repo tracks its own `v1` milestone (`git_milestone_create`).
- Each Village gets a lightweight `{village}-wiki` repo (`has_issues: false`) for roadmap + ADRs.
- When all repos in a Village hit v1 → cut Village v1 release → Voyager milestone advances.

| Layer | Tool |
|-------|------|
| Village roadmap & ADRs | Wiki on `{village}-wiki` repo |
| Village v1 target | `v1` milestone per repo |
| Cross-repo board | Forgejo org Project (one per Village) |
| Ecosystem release | `git_release_create` on the `voyager` tracking repo |

## Commits Are the Only Durable Save

Uncommitted edits live only in the working tree — a branch switch, rebase, or another
agent's operation can discard them with no recovery. **Commit as soon as a change is
coherent**, to your `claw/<task>-<shortid>` branch (never `main`), staging **explicit paths**
(`git add <paths>` — never `git add -u`/`-a`, which sweep up other agents' uncommitted edits
on a shared checkout). Small WIP commits are fine — they squash at merge; lost work cannot.

> There is **no** "Stop hook auto-commits `git add -u` and pushes to `main`" safety net —
> that older behavior is removed and superseded. Any automated commit must be branch-aware:
> refuse on `main`, stage explicit paths, and go through a self-merged PR.

## The One-Liner

> No work without an issue → plan → tests first → branch → commit referencing `#N` → PR →
> rebase + verify green → **agent self-merges** → cut a release per batch. Human is pulled
> in only on a major error. Issues live with the code; Villages aggregate cross-repo; Wikis
> hold the "why."

## Common Mistakes

- Starting work with no issue (only trivial one-liners are exempt).
- Ending at "PR is open, ready for you to merge" — a PR you opened is yours to self-merge.
- Asking "should I merge?" for a routine, green, rebased PR — merging is the assumed intent.
- Committing to `main` directly, or using `git add -u`/`-a` on a shared checkout.
- Merging without running the repo's tests first — the test pass is what replaces review.
- Committing without a `#N` reference when an issue exists.
- Switching a remote to SSH to dodge an auth failure — run `tawa login --save` instead.
- Using GitHub / `mcp__github__*` tools — everything is Forgejo at `git.tawa.pro`.
- Tracking cross-repo work as issues in a "meta" repo — issues live where the code lives;
  aggregate them with a Village Project instead.