📝 Document GitHub Flow branching model and agent task workflow
Adopt single-developer GitHub Flow: branches off main with a feature/fix/chore prefix, merged back via 'git merge --no-ff' (local PR). Releases are not triggered by pushes; only the maintainer runs 'npm run release', which tags and pushes; CI publishes to npm on the tag. Gitea is the lab; GitHub is reserved for later promotion. Replace the 'not yet settled' backlog note in AGENTS.md with concrete agent instructions: a task with subtasks gets a branch, a leaf task is worked on the current branch, and a fixed handover template (Implemented / Judgement calls / Known problems) frames the pre-merge review. Drop the stale 'MR' reference in 'Never do' (no MR workflow). Update the feedback-tier table and publishing workflow to gate CI on push to main, not PRs. Check off the branching-model backlog group and open a task for the release CI workflow (blocked on a missing Gitea runner).
This commit is contained in:
1 parent
75d605fabe
commit
06bc6bc43e
3 files changed
+39
-20
No files matched your search
@@ -26,7 +26,7 @@ Don't silence the type system to force a green run. As an agent these are forbid
|
||||
- `// oxlint-disable` / `// oxlint-disable-next-line`
|
||||
- `as` casts used to push an expression through (type-aware oxlint already flags unsafe assertions)
|
||||
|
||||
Fix the root cause with the type system instead — narrowing, generics, `satisfies`, conditional / mapped types, utility types (`NonNullable`, `Exclude`, …). TypeScript can express it; that's the intended tool. The `oxlint-disable`-location rule in [CONTRIBUTING.md § Rules the tools don't enforce](./CONTRIBUTING.md#rules-the-tools-dont-enforce) is a **human** last-resort convention (so a reviewer can spot a deliberate suppression) — it is not permission for you to add one. If the types genuinely cannot express something, stop and surface the conflict (commit message / MR) rather than suppress it.
|
||||
Fix the root cause with the type system instead — narrowing, generics, `satisfies`, conditional / mapped types, utility types (`NonNullable`, `Exclude`, …). TypeScript can express it; that's the intended tool. The `oxlint-disable`-location rule in [CONTRIBUTING.md § Rules the tools don't enforce](./CONTRIBUTING.md#rules-the-tools-dont-enforce) is a **human** last-resort convention (so a reviewer can spot a deliberate suppression) — it is not permission for you to add one. If the types genuinely cannot express something, stop and surface the conflict (commit message / handover) rather than suppress it.
|
||||
|
||||
The same applies to the checks themselves: **never `git commit --no-verify`** (or otherwise skip a pre-commit / pre-push hook). The checks are fast and offline, so a redundant run is fine — bypassing a hook to get green is the identical anti-pattern. If a commit already skipped a hook, redo it through one: `git reset --soft HEAD~1 && git commit -C <skipped-sha>`.
|
||||
|
||||
@@ -36,7 +36,23 @@ Never start a long-lived / blocking process such as `npm run watch`. It runs unt
|
||||
|
||||
`backlog.tasks` uses the vscode-todotasks format (not Markdown). A line ending in `:` is a project; every other line is a task. Status glyphs: `☐` open, `✔` done, `✘` cancelled; subtasks nest by indentation. Inline `@tags` carry metadata — `@done` / `@cancelled` mark completion, `@critical` / `@high` / `@low` / `@today` set priority. The `(…)` timestamp after `@done` is editor-generated: omit it when checking off by hand.
|
||||
|
||||
How a backlog task maps onto branches, review and release is **not yet settled** — see the branching-model task-group in `backlog.tasks`. Until that is documented, take branch and merge instructions from the user rather than inferring them.
|
||||
### Working on tasks
|
||||
|
||||
- **Task with subtasks** (a task that has indented children): create a branch off `main` using the prefix inferred from the task content (`feature/…` / `fix/…` / `chore/…`), check it out, work on each subtask with commits, then present a concise handover for the user to review. Use this fixed shape:
|
||||
|
||||
```md
|
||||
## Handover — <branch>
|
||||
|
||||
**Implemented:** <what was built, and how>
|
||||
**Judgement calls:** <where the task was unclear, and what you assumed>
|
||||
**Known problems:** <open issues, caveats, follow-ups>
|
||||
```
|
||||
|
||||
Once the user has no further objections, merge back: `git checkout main && git merge --no-ff <branch>`. The branching model is documented in [CONTRIBUTING.md § Branching model](./CONTRIBUTING.md#branching-model).
|
||||
|
||||
- **Leaf task** (no indented children): implement on the current branch and commit.
|
||||
|
||||
In both cases, follow [CONTRIBUTING.md § Testing discipline (type-driven)](./CONTRIBUTING.md#testing-discipline-type-driven). Each subtask gets one or more commits.
|
||||
|
||||
## Read these
|
||||
|
||||
|
||||
Reference in new issue
Block a user