From 560f15571eaf3f183ab1bddcdf689f2f66eeb124 Mon Sep 17 00:00:00 2001 From: vitya Date: Fri, 1 May 2026 11:32:38 +0300 Subject: [PATCH] =?UTF-8?q?feat(project-discipline):=20skill=20body=20?= =?UTF-8?q?=E2=80=94=20four=20rules=20+=20activation=20+=20out-of-scope=20?= =?UTF-8?q?[v0.1.0]?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- skills/project-discipline/SKILL.md | 104 +++++++++++++++++++++++++++++ 1 file changed, 104 insertions(+) diff --git a/skills/project-discipline/SKILL.md b/skills/project-discipline/SKILL.md index 60a0786..44a0304 100644 --- a/skills/project-discipline/SKILL.md +++ b/skills/project-discipline/SKILL.md @@ -17,3 +17,107 @@ description: > --- # project-discipline + +> Four cross-project rules. Read at session start. Apply before any other skill's defaults touch paths, branches, versions, or remote pushes. + +## When this runs + +**At session start** — when `CLAUDE.md` contains the line `follow project discipline`. The skill is a policy document; the agent reads it and applies the four rules to all subsequent work in the session. + +**On explicit reference** — when the user says "use project discipline", "соблюди дисциплину", "проектные правила", "что у меня по правилам?", or close variants asking about/applying the rules. + +The skill itself takes no actions and has no external side-effects. It instructs the agent how to behave. + +## Rule 1 — Project conventions override skill defaults + +Before applying defaults from any other skill (superpowers, frontend-design, mcp-builder, etc.), read in this order: + +1. `CLAUDE.md` in the project root. +2. `.wiki/CLAUDE.md` (if it exists). +3. `.tasks/STATUS.md` (if it exists). + +Any path, format, or workflow explicitly stated in those files **overrides the skill default**. + +Concrete consequences: + +- **Specs / design documents** go to `.wiki/concepts/-design.md`, **not** `docs/superpowers/specs/`. +- **Task tracking / implementation plans** go to `.tasks/.md` plus a board entry in `.tasks/STATUS.md` (the `using-tasks` format), **not** `docs/superpowers/plans/` or any inline-in-chat plan format. +- **Frontmatter, naming conventions, log format** — as described in the project's `.wiki/CLAUDE.md`. + +If no convention is stated explicitly — fall back to the skill default. + +## Rule 2 — Master-only + +All work happens on the repo's main integration branch — usually `master`, but if a project uses `main`, treat `main` as equivalent. + +- No `git checkout -b feature/foo` for solo work. +- Sync with remote: `git pull --ff-only` or `git pull --rebase`. **No merge commits** for solo work. +- If a task genuinely requires isolation (large experiment, risky refactor with rollback potential, multi-day work with intermediate WIP commits) — **ask** the user: "this needs its own branch, ok?" — and wait for explicit approval. Without approval, work continues on master. + +If the agent finds itself on a non-main branch (after a manual `git checkout`) or in detached HEAD — report it and ask whether to return to master before working. + +## Rule 3 — Versioning discipline + +When editing any artifact with a semver field, **bump the version before committing** per: + +- **MAJOR** (`X+1.0.0`) — breaks the contract. Renames, removed triggers, layout changes, removed public functions, breaking API change. +- **MINOR** (`X.Y+1.0`) — adds capability without breaking. New trigger, new optional step, new public function. +- **PATCH** (`X.Y.Z+1`) — wording / clarity / typo fixes with no behavior change. + +The bump is recorded in the commit message: `feat(): … [vX.Y.Z]` or whatever convention the project uses (see Rule 1). + +**Applies to:** `skills//SKILL.md` (`version:` in frontmatter), `package.json` (`"version":`), `pyproject.toml` (`version =`), `Cargo.toml` (`version =`), and any other semver field in any other manifest. + +**If the artifact is packaged** as `dist/.skill`, `dist/*.tgz`, etc. — **rebuild** the package in the same or the next commit. Forgotten dist artifacts are a common cause of deploying stale binaries. + +**First edit of an unversioned artifact** that COULD have a semver field (a new skill without `version:`, a new `package.json` without `"version":`) — **add** `version: 0.1.0` (or its equivalent) before committing; do not bump anything. + +**Does not apply to:** artifacts with no semver field and no potential for one (wiki concept pages, README.md, shell scripts without a public interface). + +## Rule 4 — Commit yes, push no (session-scoped) + +**Every session starts in ask-before-push mode.** On every `git push`, ask: + +> Готов push'нуть в `/` (N коммитов: ). Ок? + +(or its English equivalent if the user is communicating in English) and wait for explicit `yes` / `да` / `push` / equivalent. Without confirmation — do not push. + +**Granting auto-push within a session.** When the user says: + +- "разреши автопуш" / "allow auto-push" / "автопуш ок" / equivalent + +— push without further confirmation until the end of the session or until revoked. + +**Revoking auto-push within a session.** When the user says: + +- "отзови автопуш" / "revoke auto-push" / "снова спрашивай" / equivalent + +— return to ask-before-push mode. + +**Session end resets to ask-mode.** The next session starts asking again, regardless of what was granted in the previous one. This is intentional: a grant is given for the current context (user nearby, consciously decided pushes are safe), and should not survive a context switch. + +**Always ask, even with active grant:** + +- `git push --force` / `--force-with-lease` (history rewrite); +- `git push origin --delete ` (branch deletion); +- push to a remote/branch other than the current tracked upstream (`git push other-remote ...`, `git push origin other-branch`); +- push to the main branch that would require non-fast-forward (i.e. would need force). + +A grant covers ordinary fast-forward push to the configured upstream. Anything else is a separate class of operation and needs its own decision. + +**What counts as "push":** only `git push` family commands. Local commits, `git stash push`, etc. are not push; the grant does not apply. + +## Out of scope + +The skill **does not**: + +- modify `CLAUDE.md` (that's `project-bootstrap`'s job); +- enforce rules via git hooks / pre-commit / CI (this is agent discipline, not tooling); +- manage `settings.json` permissions (that's `update-config`); +- check the existence of `.wiki/` / `.tasks/` (that's `setup-wiki` / `setup-tasks` / `project-bootstrap`); if a project doesn't have them, Rule 1 simply finds no overrides and falls back to skill defaults. + +## Why this exists + +In a tightly-disciplined repo (`claude-skills`) the four rules already hold by accident — the agent reads `.wiki/CLAUDE.md`, knows specs go to `.wiki/concepts/`, knows to bump `version:`, knows not to push without confirmation. In **other** projects of the same user, that discipline does not transfer: the agent uses `superpowers`' default `docs/superpowers/specs/`, branches on a whim, forgets `version:` bumps, and pushes without asking. This skill makes the discipline explicit and portable. + +Full design rationale (why one skill instead of four, why a skill instead of inline `CLAUDE.md` lines, scope of each rule, push-permission mechanism choice) lives in `.wiki/concepts/project-discipline-design.md` (in this repo; in other projects bootstrapped from this repo, the design lives in `claude-skills`).