.gitea/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,19 @@
+## WHAT
+
+<!-- What changed? -->
+
+## WHY
+
+<!-- Why this change? -->
+
+## HOW
+
+<!-- How was it implemented? Include verification. -->
+
+## Linear Issue
+
+<!-- Required. Identifier + URL, e.g. MAN-133 https://linear.app/maneco-workspace/issue/MAN-133 -->
+
+## Comments
+
+<!-- Notes for reviewers. Screenshots, follow-ups, out of scope. -->

.github/pull_request_template.md

@@ -0,0 +1,19 @@
+## WHAT
+
+<!-- What changed? -->
+
+## WHY
+
+<!-- Why this change? -->
+
+## HOW
+
+<!-- How was it implemented? Include verification. -->
+
+## Linear Issue
+
+<!-- Required. Identifier + URL, e.g. MAN-133 https://linear.app/maneco-workspace/issue/MAN-133 -->
+
+## Comments
+
+<!-- Notes for reviewers. Screenshots, follow-ups, out of scope. -->

AGENTS.md

@@ -18,7 +18,19 @@ Feature and browser tests require the `amare_test` PostgreSQL database configure
 
 ## Worktrees
 
-Always work in a git worktree created from the `main` ref — never modify `main` directly and never commit from the primary working tree. Create a dedicated worktree per feature/branch with `git worktree add -b <branch> <path> main`. On finishing work, create a PR, watch CI until green, then merge it. Clean up the worktree with `git worktree remove` after merge.
+Always work in a git worktree created from the `main` ref — never modify `main` directly and never commit from the primary working tree. Create a dedicated worktree per feature/branch with `git worktree add -b <branch> <path> main`. Include the Linear identifier in the branch name (e.g. `docs/man-132-…`). When the SDLC gate below is green, commit and open the PR without asking. Watch CI until green, then merge. Clean up the worktree with `git worktree remove` after merge.
+
+## Agent SDLC (do not ask)
+
+Never ask whether to commit or open a PR. After each complete slice of work, ship it:
+
+1. **Work is done** in a Linear-linked worktree.
+2. **Tests are written or updated** for the changed layer. Skip new tests only when the change has no runtime impact (docs, templates, static config).
+3. **Pre-commit passes** (`composer pint:check` and `composer phpstan`). Do not `--no-verify`. If the hook fails, fix and rerun.
+4. **Commit** with Conventional Commits. Cite the Linear identifier.
+5. **Push and open the Gitea PR** (`tea pulls create`) using `.gitea/PULL_REQUEST_TEMPLATE.md` (WHAT / WHY / HOW / Linear Issue / Comments). Attach the PR URL on the Linear issue via `save_issue` `links`. GitHub is the legacy mirror only.
+
+Do not wait for "pode commitar?" or "abre o PR?".
 
 ## Git Hooks (husky)
 
@@ -41,7 +53,7 @@ Tests use Pest 4; browser coverage uses Pest Browser/Playwright. Tests are verif
 
 ## Commit & Pull Request Guidelines
 
-History follows Conventional Commit-style subjects, for example `feat: Fase 0 — Fundação`. Use `<type>: <imperative summary>` (`feat`, `fix`, `docs`, `test`, `chore`) and keep commits focused. Pull requests should explain scope, link the relevant issue or OpenSpec requirement, list verification commands, and include screenshots for UI changes. Ensure all CI jobs pass.
+History follows Conventional Commit-style subjects, for example `feat: Fase 0 — Fundação`. Use `<type>: <imperative summary>` (`feat`, `fix`, `docs`, `test`, `chore`) and keep commits focused. Fill the PR template (WHAT / WHY / HOW / Linear Issue / Comments). **Linear Issue is required** (identifier + URL). An OpenSpec change is extra context, not a substitute. Include verification commands and screenshots for UI changes. Ensure all CI jobs pass. After pre-commit is green, commit and open the PR — do not ask.
 
 ## Security & Configuration
 
@@ -59,6 +71,8 @@ The design system lives in `DESIGN.md` (palette, typography, layout, do's and do
 
 Issues live in Linear, driven through the Linear MCP tools. See `docs/agents/issue-tracker.md` for workspace, team, and tool conventions. The repo ships no `.mcp.json`, so the Linear MCP has to be enabled for the session before those tools exist — if it isn't, report that instead of silently falling back to another tracker.
 
+**Every piece of work and every PR must be tied to a Linear issue.** Do not create a branch, worktree, or PR until an issue exists (identifier like `MAN-132`). If the user did not give one, search Linear first; if none fits, create it with `save_issue` on team `Maneco-workspace` before starting. Put the identifier in the branch name. Cite identifier + URL in the PR body. After opening the PR, attach the PR URL on the issue via `save_issue` `links`. Do not start untracked work.
+
 ### Triage labels
 
 Default vocabulary: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`. See `docs/agents/triage-labels.md`.

docs/agents/issue-tracker.md

@@ -17,6 +17,16 @@ Issues and specs for this repo live in Linear. Use the Linear MCP tools for all
 - **Link work**: `save_issue` with `project`, `cycle`, `parentId`, `blocks` / `blockedBy` (relations are append-only).
 - **Cross-link to a PR**: attach the PR URL via `save_issue` `links`.
 
+## Required: issue before work and before PR
+
+Every branch, worktree, and pull request in this repo must be tied to a Linear issue.
+
+1. **Starting work:** require an identifier (e.g. `MAN-132`). If the user did not give one, search Linear. If none fits, create the issue with `save_issue` on team `Maneco-workspace` *before* creating a branch or worktree.
+2. **Branch:** include the identifier (`docs/man-132-…`, `feat/man-126-…`).
+3. **PR:** cite identifier + URL in the body. An OpenSpec change is extra context, not a substitute.
+4. **After the PR exists:** attach the PR URL on the issue via `save_issue` `links`. Do this as part of the automatic SDLC in `AGENTS.md` — do not ask before opening the PR.
+5. If Linear MCP is unavailable, stop and report — do not start untracked work.
+
 ## When a skill says "publish to the issue tracker"
 
 Create a Linear issue with `save_issue` on team `Maneco-workspace`.