diff --git a/dist/mappa-vitya-project-discipline.skill b/dist/mappa-vitya-project-discipline.skill new file mode 100644 index 0000000..ff95913 Binary files /dev/null and b/dist/mappa-vitya-project-discipline.skill differ diff --git a/dist/project-bootstrap.skill b/dist/project-bootstrap.skill index f37ca50..34066ed 100644 Binary files a/dist/project-bootstrap.skill and b/dist/project-bootstrap.skill differ diff --git a/dist/project-discipline.skill b/dist/project-discipline.skill deleted file mode 100644 index 5f102e2..0000000 Binary files a/dist/project-discipline.skill and /dev/null differ diff --git a/skills/mappa-vitya-project-discipline/README.md b/skills/mappa-vitya-project-discipline/README.md new file mode 100644 index 0000000..12a938a --- /dev/null +++ b/skills/mappa-vitya-project-discipline/README.md @@ -0,0 +1,59 @@ +# mappa-vitya-project-discipline + +Vitya-flavored cross-project discipline policy skill for a mappa knowledge zone. +Codifies the five work rules (project-canon via mappa, master-only, semver, +push) PLUS four mappa-canon rules (rg-only search, live-verify after reload, +knowledge-first, durable-knowledge-to-wiki). + +## When it triggers + +- **Session start** — when `AGENTS.md` contains the line + `follow mappa-vitya project discipline` (inserted by `mappa-bootstrap`, which + selects the project's methodology flavor). +- **In-chat** — when the user says "use project discipline", "соблюди + дисциплину", "проектные правила", "follow project discipline", or close + variants. + +## The rules + +1. **Project canon is a mappa wiki entity, not files.** Read the project's + `AGENTS` entity (`wiki_get(project,'AGENTS')`), NOT `.wiki/CLAUDE.md` / + `.tasks/` (file channel closed). Before any wiki work — run `mappa-knowledge` + first. +2. **Master-only.** All work on `master` (or `main`). No feature branches + without explicit user approval. +3. **Semver discipline.** Bump `version:` in `SKILL.md` / `package.json` / + `pyproject.toml` on every edit per MAJOR / MINOR / PATCH; record in commit + message; rebuild `dist/` artifacts after. +4. **Push freely by default.** No confirmation needed for push; a local push + gate (`push gate: ask` in AGENTS entity, or explicit operator word) + overrides per project. Force / delete / non-ff push always asks. +5. **Transit-zone / brainstorm workspaces (mappa channel).** Brainstorm + artifacts go to a mappa brainstorm entity, not `.brainstorm/*.md`. Only + promote to a wiki concept when the user explicitly directs. + +## Mappa-canon rules + +- **Rule G — rg-only search.** Never walk node_modules/dist/build with + `grep -r`/`find`/`ag`/`ack`. Use `rg` (gitignore-aware); never `rg --no-ignore`. +- **Rule K — knowledge-first.** Run `mappa-knowledge` before any wiki work. +- **Rule L — live-verify after reload.** Infra changes verified in a live + interactive session, not headless. +- **Rule D — durable knowledge to mappa wiki.** Never `memory/` / local files; + go to a mappa wiki entity. + +## Prerequisites + +- `mappa` MCP server available (`mcp__mappa__*`) to read the canon. +- `mappa-knowledge` skill installed. +- Methodology flavor selected by `mappa-bootstrap` (the source of the + `follow mappa-vitya project discipline` trigger line). + +## Related + +- `mappa-bootstrap` — picks the methodology flavor per project and inserts the + trigger line. +- `project-bootstrap` — writes the project scaffold (removed the legacy + `follow project discipline` trigger; the generic skill was replaced by the + per-flavor `mappa-vitya-project-discipline`). +- `mappa-vitya-brainstorming` — the brainstorm METHODOLOGY for a mappa zone. diff --git a/skills/mappa-vitya-project-discipline/SKILL.md b/skills/mappa-vitya-project-discipline/SKILL.md new file mode 100644 index 0000000..35b403f --- /dev/null +++ b/skills/mappa-vitya-project-discipline/SKILL.md @@ -0,0 +1,264 @@ +--- +name: mappa-vitya-project-discipline +author: ours +version: 1.0.0 +description: > + The vitya-flavored cross-project discipline for a mappa knowledge zone — + codifies the work rules (project-canon via mappa, master-only, semver, push) + PLUS the four mappa-canon rules (rg-only search, live-verify after reload, + knowledge-first, durable-knowledge-to-wiki). The mappa METHODOLOGY for a + project is selected by mappa-bootstrap, not hardcoded here. Use when the user + says "follow project discipline", "соблюди дисциплину", "проектные правила", + "что у меня по правилам?", "use project discipline", or when AGENTS.md + contains "follow mappa-vitya project discipline". NOT for: the method SELECTION + itself (→ mappa-bootstrap), a project's own AGENTS.md content (→ project-bootstrap). +--- + +# mappa-vitya-project-discipline + +**This is the vitya-flavored cross-project *discipline* skill.** It tells you +the work rules to apply in a project on a mappa-based setup. It is a +policy document — the agent reads it and behaves; it takes no actions and has +no external side-effects. + +Run the discipline **anywhere**, in **any project**, by **any agent**. The +methodology flavor is chosen per-project by `mappa-bootstrap` (this is the +`mappa-vitya-*` flavor). The skill itself does NOT select or swap methodology — +that is `mappa-bootstrap`'s job. + +**Boundary with `mappa-bootstrap`:** this skill defines WHAT the discipline is +for the vitya flavor. `mappa-bootstrap` decides WHETHER/WHICH methodology a +project uses (by detecting methodology traces in AGENTS.md and installing / +delivering the matching skills). The trigger that activates this skill — +`follow mappa-vitya project discipline` — is inserted by `mappa-bootstrap`, not +baked into a project by hand as canon rules here. + +## When to use + +- AGENTS.md contains `follow mappa-vitya project discipline` — apply the rules + for the rest of the session. +- User says "use project discipline", "соблюди дисциплину", "проектные + правила", "что у меня по правилам?", "follow project discipline", or asks + about/applying the rules. + +**NOT for:** the methodology selection (→ `mappa-bootstrap`), writing a +project's own AGENTS.md content (→ `project-bootstrap`), or the mappa +brainstorm/promotion method (→ `mappa-vitya-brainstorming`). + +## The rules + +### Rule 1 — Project canon is a mappa wiki entity, not files + +Before applying default behavior, read the project's canon from **mappa**, not +from files. On a mappa-based setup the file channel (`.wiki/CLAUDE.md`, +`.tasks/`, `.brainstorm/`) is **closed** — the canonical contract lives as +mappa entities. + +Read order: + +1. The project's mappa **wiki entity `AGENTS`** — `wiki_get(project, 'AGENTS')` + (or for the boss-zone, `wiki_get('.workshop','AGENTS')`). This is the + project's canonical contract. +2. The mappa **handoff** entity (session-start contract) and **inbox** letters. +3. The workspace/zone contract via `.workshop` AGENTS entity where relevant. + +Any path, format, or workflow explicitly stated in the project's AGENTS entity +**overrides this skill's default.** No file-based `.wiki/CLAUDE.md` / +`.tasks/` lookups — those are legacy/stubs («не читать, не править»). + +**Mandatory precursor:** before ANY wiki work — run `mappa-knowledge` first. It +loads the project's AGENTS entity and the read/ingest contract. Never write a +wiki concept without running it first (this is also mappa-canon rule **K**). + +Concrete consequences: + +- **Specs / design decisions** → a mappa **wiki concept** (`wiki_create`). +- **Tasks / implementation plans** → mappa **task entities** (`task_create`). +- **Brainstorm buffers** → mappa **brainstorm entities** (`brainstorm_create`), + not `.brainstorm/*.md` files. +- If no convention is stated — 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 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`, `pyproject.toml`, `Cargo.toml`, and any other semver field. + +**If the artifact is packaged** as `dist/.skill` — **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 — **add** +`version: 0.1.0` before committing; do not bump anything. + +### Rule 4 — Push freely, gate only where a local gate exists + +**Default: push freely.** An ordinary fast-forward `git push` to the configured +upstream needs no per-push confirmation. No ask-before-push mode by default. + +**Push gate** (replaces the free-push default for a specific project). A push +gate makes every push require confirmation — it is set up ONE of two ways: + +- **On the record** — the project's AGENTS.md / AGENTS entity declares a push + gate (e.g. `push gate: ask`); it applies persistently for that project. +- **Explicitly, by the operator, in the session** — the operator says "push + gate" / "спрашивай перед пушем"; it applies for the rest of that session OR + until explicitly lifted. + +Either way, when a gate is active, EVERY push to that project asks first. + +**Always ask:** `git push --force` / `--force-with-lease`; branch deletion; +push to a remote/branch other than the current tracked upstream; push to the +main branch that would require non-fast-forward. + +**What counts as "push":** only `git push` family commands. Local commits, +`git stash push`, etc. are not push. + +### Rule 5 — Transit-zone / brainstorm workspaces (mappa channel) + +Some workspaces are **transit zones** — discussion areas where brainstorm +artifacts are NOT auto-promoted to project wikis. On a mappa setup the default +destination is the mappa brainstorm entity, not a file. + +**Default destination for brainstorm artifacts:** +- **In-progress brainstorm outputs** → a mappa **brainstorm entity** + (status=buffer). `.brainstorm/*.md` files are legacy; the file channel is + closed. +- **Mature, cross-cutting outputs** → mappa **wiki concept** (via + `wiki_create`) — **only** when the user explicitly directs this. + +**Agent must NOT auto-promote** brainstorm artifacts to wikis by analogy with +Rule 1. The convergence-moment (move from buffer to permanent wiki) is a user +decision, not an automatic action. + +**When in doubt:** ask the user "this goes to a mappa brainstorm entity, or +should I promote it to a wiki concept?" rather than assuming. + +## Mappa-canon rules + +These four rules are the mappa-canon discipline for any mappa-based zone. They +apply in addition to the five above. + +### Rule G — rg-only search (never walk node_modules/dist/build) + +⛔ Never walk `node_modules/`, `dist/`, `build/`, `.nuxt/`, or any parent tree +containing them with non-gitignore-aware search tools. + +- Use **`rg`** (gitignore-aware). NEVER `rg --no-ignore` / `-u` — those bypass + the ignore protection and walk node_modules again. +- Also no `grep -r` / `-R` / `--recursive`, `ag`, `ack`, `find … -exec grep`. +- `grep --include` filters result file names, NOT directory traversal — it still + walks every node_modules entry. `| grep -v node_modules` filters after the + walk, doesn't save you. + +Rationale: measured 3701s (grep walk of a projects tree) vs 0s (rg) — +2026-08-26 incident, task:1233. + +### Rule K — knowledge-first (mappa-knowledge before any wiki) + +Before ANY work with a project's wiki — run the `mappa-knowledge` skill FIRST, +not after the first step. It loads the project's AGENTS entity and the +read/ingest contract. Never write a wiki concept, ingest, or query without +running it first. (Violation noted twice in one session — fixed by rule, not +excuses.) + +### Rule L — live-verify after reload + +Infrastructure changes (MCP wiring, adapters, configs, bridges) must be +verified in a **live interactive session after reload**, not just by headless +checks. "Fixed, verified headless" is NOT enough — precedent: the +`mappa-http-adapter` (2026-08-25) passed headless but failed real use. + +After an infra change, minimally: reload the configuration + make a real +tool call in a live session. + +### Rule D — durable knowledge → mappa wiki, never memory/local files + +Durable knowledge (domain, ops, methodology) goes to a **mappa wiki entity**, +NOT to local per-project memory (`~/.claude/.../memory/`) or repo files. Memory +is not queryable by peer sessions, not graph-linked, and is lost. If you catch +yourself writing durable knowledge to `memory/` or a local file — stop, redirect +to a mappa wiki entity (domain → target project's wiki; workshop-meta → +`.workshop` wiki entity). User: "все важное писать в вики" (2026-06-18). + +## Quick reference + +| Decision | Answer | +|---|---| +| Where is the project canon | mappa wiki entity `AGENTS` — NOT `.wiki/CLAUDE.md` / `.tasks/`. | +| Before any wiki work | Run `mappa-knowledge` first (Rule K). | +| Where do specs/design go | mappa wiki concept (`wiki_create`). | +| Where do tasks go | mappa task entities (`task_create`). | +| Where do brainstorm buffers live | mappa brainstorm entity — NOT `.brainstorm/*.md`. | +| Search a codebase | `rg` only — never `grep -r`/`find` over node_modules/dist (Rule G). | +| Infra change verification | Live session after reload, not headless (Rule L). | +| Durable knowledge | mappa wiki, never `memory/` / local files (Rule D). | +| Method flavor / selection | `mappa-bootstrap` selects; this skill only defines the vitya rules. | + +## Common rationalizations (excuse → reality) + +| Excuse | Reality | +|---|---| +| "Let me just grep -r to be safe" | Use `rg`; `grep -r` walks every node_modules (Rule G). | +| "I'll check CLAUDE.md for conventions" | File channel is closed; read the mappa `AGENTS` entity (Rule 1). | +| "Fixed and typecheck passed — done" | Infra changes need live-verify after reload, not headless (Rule L). | +| "I'll jot this in my project memory" | Durable knowledge goes to a mappa wiki, never `memory/` (Rule D). | +| "I'll write the spec to a repo file" | Spec goes to a mappa wiki concept; run `mappa-knowledge` first (Rule K). | +| "The method is baked into this repo" | Method flavor is per-project, chosen by `mappa-bootstrap`. | + +## Red flags (all = STOP and re-orient) + +- You are searching with `grep -r` / `find` over a tree that can contain + node_modules/dist/build. +- You are reading `.wiki/CLAUDE.md` / `.tasks/` as the project canon on a + mappa-based setup. +- You are about to write durable knowledge to `memory/` or a local file. +- You are about to write a spec to a repo file rather than a mappa wiki concept. +- You changed an infra/MCP component and only "verified headless". +- You are doing wiki work without running `mappa-knowledge` first. +- You assume this project must use the vitya methodology — let `mappa-bootstrap` + make that selection. + +## Out of scope + +- Does NOT select or swap the methodology flavor (→ `mappa-bootstrap`). +- Does NOT write a project's AGENTS.md content (→ `project-bootstrap`). +- Does NOT run the brainstorm/promotion method (→ `mappa-vitya-brainstorming`). +- Does NOT install skills (→ `mappa-bootstrap` / `update-skills`). + +## Cross-agent applicability + +Behavior discipline with a mappa-media dependency. The mappa tool names are +concrete (this zone runs on mappa); the RULES (read the durable canonical +contract, master-only, semver, push-gate, rg-only search, live-verify, durable +knowledge to the wiki) transfer to any mappa-based zone. On a non-mappa setup, +substitute the corresponding knowledge channels. + +`mappa-knowledge` is a mandatory precursor before any wiki work (Rule K): it +loads the project's AGENTS entity and the read/ingest contract. diff --git a/skills/project-bootstrap/README.md b/skills/project-bootstrap/README.md index d5e0bb9..2af7078 100644 --- a/skills/project-bootstrap/README.md +++ b/skills/project-bootstrap/README.md @@ -53,7 +53,7 @@ Karpathy / `.tasks/` (см. using-wiki/using-tasks, legacy-раздел). 3. **Steps 1–5.** Create or skip each piece in order — git, README, вики/таски (mappa, см. using-wiki/using-tasks), `AGENTS.md` + `CLAUDE.md` pointer. 4. **Step 5.5.** Write `bootstrap-manifest.md` recording the versions of - `project-bootstrap`, `project-discipline`, `setup-interns`, and + `project-bootstrap`, `setup-interns`, and `using-interns` used. 5. **Step 5.6.** Skill dependencies check. Walk the canonical trigger list in `AGENTS.md`, look each up in an embedded `trigger → fulfiller` map, @@ -102,8 +102,9 @@ target with `CLAUDE_SKILLS_DIR=/path bash scripts/install.sh …`. - [`using-wiki`](../using-wiki/) — runtime policy for the mappa wiki (v2). - [`using-tasks`](../using-tasks/) — runtime policy for the mappa task board (v2). -- [`project-discipline`](../project-discipline/) — cross-project rules - activated by the `follow project discipline` trigger. +- [`mappa-vitya-project-discipline`](../mappa-vitya-project-discipline/) + — vitya-flavored cross-project discipline (activated per-project by + `mappa-bootstrap`, which selects the methodology flavor). - [`setup-interns`](../setup-interns/), [`using-interns`](../using-interns/) — pair behind the `delegate to interns when allowed` trigger; cheap-LLM delegation under a per-session permission grant. diff --git a/skills/project-bootstrap/SKILL.md b/skills/project-bootstrap/SKILL.md index 01da295..ccf314e 100644 --- a/skills/project-bootstrap/SKILL.md +++ b/skills/project-bootstrap/SKILL.md @@ -1,7 +1,7 @@ --- name: project-bootstrap author: ours -version: 3.1.0 +version: 3.2.0 description: > Initializes or upgrades a project in the current folder: git, .gitignore, README.md, .wiki/ using Karpathy's method, .tasks/ for task tracking, AGENTS.md (canon) with @@ -391,7 +391,6 @@ use project wiki use task management system check across all projects pull remote before work -follow project discipline follow tdd-criteria delegate to interns when allowed recommend, don't menu @@ -413,15 +412,6 @@ upstream — never auto-merges, stashes, or pushes. Install the skill on the hos if `pulling-before-work` is not in `~/.claude/skills/`; otherwise the trigger is silently dead like any other absent skill. -The `follow project discipline` line activates the `project-discipline` skill, -which codifies four cross-project rules: (1) project AGENTS.md / CLAUDE.md / -.wiki/CLAUDE.md / .tasks/ override defaults from any other skill; (2) all work on master/main, -no feature branches without explicit user approval; (3) version bump on every -edit of versioned artifacts per semver, recorded in commit; (4) commit freely, -push only after explicit per-session approval. Install the skill on the host -if `project-discipline` is not in `~/.claude/skills/`; otherwise the trigger is -silently dead like any other absent skill. - The `follow tdd-criteria` line activates the `tdd-criteria` skill, which enforces test-driven development by default with four bright-line carve-outs (visual CSS, spike exploration, oneshot scripts, pure wrappers) and four anti-loophole rules @@ -435,8 +425,8 @@ which lets Claude offload predictable bulk I/O and summarization tasks (reading 3+ files, distilling long transcripts) to cheap intern LLMs via the local `interns` MCP server (`mcp__interns__bulk_text_read`, `mcp__interns__transcript_distill`, etc.) — saves Anthropic quota at ~125× the -per-call cost reduction on bulk reads. Per-session permission grant mirrors -`project-discipline` Rule 4: ask-mode default, conversational grant / revoke, +per-call cost reduction on bulk reads. Per-session permission grant mirrors the +`mappa-vitya-project-discipline` Rule 4: ask-mode default, conversational grant / revoke, always-ask paths for `.env` / secrets / keys / SSH credentials even with an active grant, session-end reset. The skill is a no-op until the `interns` MCP server is registered — install via `setup-interns` on a fresh machine if @@ -479,7 +469,6 @@ Skills used to initialize this project's `.wiki/` and `.tasks/` layout, with the | Skill | Version | Role | |---|---|---| | `project-bootstrap` | | orchestrator | -| `project-discipline` | | cross-project policy | | `setup-interns` | | interns MCP server install (one-time, per machine) | | `using-interns` | | interns runtime policy + per-session permission grant | | `mappa-*` (методика, модуль 5.7) | | mappa-циклы: session-orient / task-work / knowledge / messaging / delegation / brainstorm-promote / closing-ritual | @@ -519,7 +508,6 @@ Mismatch between template and map → silent gaps in the recommendation. | `check across all projects` | mappa (`mcp__mappa__*`) | MCP | `mcpServers.mappa` in `~/.claude.json` | — | | `pull remote before work` | `pulling-before-work` | skill | `~/.claude/skills/pulling-before-work/SKILL.md` | `bash scripts/install.sh pulling-before-work` | | `session handoff: read on start, write on end` | `session-handoff` | skill | `~/.claude/skills/session-handoff/SKILL.md` | `bash scripts/install.sh session-handoff` | -| `follow project discipline` | `project-discipline` | skill | `~/.claude/skills/project-discipline/SKILL.md` | `bash scripts/install.sh project-discipline` | | `follow tdd-criteria` | `tdd-criteria` | skill | `~/.claude/skills/tdd-criteria/SKILL.md` | `bash scripts/install.sh tdd-criteria` | | `delegate to interns when allowed` | `using-interns` | skill | `~/.claude/skills/using-interns/SKILL.md` | `bash scripts/install.sh using-interns` | | `recommend, don't menu` | `recommend-dont-menu` | skill | `~/.claude/skills/recommend-dont-menu/SKILL.md` | `bash scripts/install.sh recommend-dont-menu` | diff --git a/skills/project-bootstrap/assets/AGENTS.md.template b/skills/project-bootstrap/assets/AGENTS.md.template index ae78067..4c3b6df 100644 --- a/skills/project-bootstrap/assets/AGENTS.md.template +++ b/skills/project-bootstrap/assets/AGENTS.md.template @@ -21,7 +21,6 @@ use task management system check across all projects pull remote before work session handoff: read on start, write on end -follow project discipline follow tdd-criteria delegate to interns when allowed recommend, don't menu diff --git a/skills/project-discipline/README.md b/skills/project-discipline/README.md deleted file mode 100644 index 1087aed..0000000 --- a/skills/project-discipline/README.md +++ /dev/null @@ -1,29 +0,0 @@ -# project-discipline - -Policy skill that codifies four cross-project discipline rules so the same -guarantees that hold in a tightly-maintained repo apply everywhere. - -## When it triggers - -- **Session start** — when `AGENTS.md` contains the line `follow project discipline` (added by `project-bootstrap` v2.0.0+). -- **In-chat** — when the user says "use project discipline", "соблюди дисциплину", "проектные правила", or close variants. - -## The four rules - -1. **Project conventions over skill defaults.** `AGENTS.md` / `.wiki/CLAUDE.md` / `.tasks/` override any other skill's defaults. Specs go to `.wiki/concepts/`, tasks to `.tasks/`. -2. **Master-only.** All work on `master` (or `main`). No feature branches without explicit user approval. -3. **Semver discipline.** Bump `version:` in `SKILL.md` / `package.json` / `pyproject.toml` on every edit per MAJOR / MINOR / PATCH; record in commit message; rebuild `dist/` artifacts after. -4. **Push freely by default.** No confirmation needed for push; a local push-gate skill (e.g. books — auto-deploy) overrides per project. Force / delete / non-ff push always asks. - -## Prerequisites - -None. The skill is a textual policy document; it takes no actions and has no -external dependencies. Activate it by adding `follow project discipline` to -`AGENTS.md` (or use `project-bootstrap` v2.0.0+ which adds it automatically). - -## Related - -- `project-bootstrap` (v2.0.0+) — adds the trigger line to new and existing projects' `AGENTS.md`. -- `pulling-before-work` — companion skill activated by the canonical template; pulls origin once at session start (`git pull --ff-only`). -- `using-tasks` / `using-wiki` — the format conventions Rule 1 routes work into. -- `.wiki/concepts/project-discipline-design.md` (in `skills`) — full design rationale. diff --git a/skills/project-discipline/SKILL.md b/skills/project-discipline/SKILL.md deleted file mode 100644 index 59e84ea..0000000 --- a/skills/project-discipline/SKILL.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -name: project-discipline -author: ours -version: 0.2.2 -description: > - Codifies five cross-project discipline rules: (1) project AGENTS.md / - .wiki/CLAUDE.md / .tasks/ override defaults from other skills (specs → - .wiki/concepts/, tasks → .tasks/); (2) master-only, no feature branches - without approval; (3) semver bump on every edit of versioned artifacts - (SKILL.md, package.json, pyproject.toml), recorded in commit; - (4) push freely by default — no confirmation needed; - a local push-gate skill (e.g. books — auto-deploy) - overrides per project; force/delete/non-ff always ask; - (5) transit/brainstorm workspaces — artifacts to .brainstorm/ or global wiki - only via explicit user direction. Activated by "follow project discipline" - trigger in AGENTS.md (added by project-bootstrap v2.0.0+). ---- - -# 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 `AGENTS.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 (frontend-design, mcp-builder, etc.), read in this order: - -1. `AGENTS.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**. (CLAUDE.md, where present, is a legacy pointer — read it, then follow the canon in AGENTS.md.) - -Concrete consequences: - -- **Specs / design documents** go to `.wiki/concepts/-design.md`. -- **Task tracking / implementation plans** go to `.tasks/.md` plus a board entry in `.tasks/STATUS.md` (the `using-tasks` 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 — Push freely, gate only where a local gate exists - -**Default: push freely.** An ordinary fast-forward `git push` to the configured -upstream needs no per-push confirmation. No ask-before-push mode by default. - -**Push gate** (replaces the free-push default for a specific project). A push -gate makes every push require confirmation — it is set up ONE of two ways: - -- **On the record** — the project's `AGENTS.md` declares a push gate (e.g. - `push gate: ask`); it applies persistently for that project. This overrides -the free-push default for as long as that line is in `AGENTS.md`. -- **Explicitly, by the operator, in the session** — the operator says "push - gate" / "спрашивай перед пушем"; it applies for the rest of that session - OR until the operator explicitly lifts it ("сними пуш-гейт" / "push freely"). - -Either way, when a gate is active, EVERY push to that project asks first. -This rule's free-push default does not apply while a gate is active. - -**Always ask:** - -- `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). - -Anything else is an ordinary fast-forward push and proceeds without a gate. - -**What counts as "push":** only `git push` family commands. Local commits, `git stash push`, etc. are not push. - -## Rule 5 — Transit-zone / brainstorm workspaces - -Some workspaces are **transit zones** — discussion areas with no `.tasks/`, where brainstorm artifacts are explicitly NOT auto-promoted to project wikis. - -**Default destination for brainstorm artifacts:** -- **In-progress brainstorm outputs** → `.brainstorm/.md` (or whatever the workspace's README/AGENTS.md declares) -- **Mature, cross-cutting outputs** → `~/projects/.wiki/concepts/-design.md` via `mcp__projects-meta__knowledge_ingest` — **only** when user explicitly directs this - -**Agent must NOT auto-promote** brainstorm artifacts to global wikis by analogy with Rule 1. Convergence-moment (move from workspace to permanent wiki) is a user decision, not an automatic action. - -**Example:** `~/projects/.meeting-room/` is a transit zone. Its AGENTS.md explicitly states "no `.tasks/`, transit zone, artifacts go to `.brainstorm/` or global wiki via user command." Rule 1's "project conventions override" applies, but the override is explicit in the workspace contract — auto-promotion by analogy would violate that contract. - -**When in doubt:** ask the user "this goes to `.brainstorm/`, or should I promote to shared wiki?" rather than assuming. - -## Out of scope - -The skill **does not**: - -- modify `AGENTS.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/` on disk (мета в mappa, решение 14/15: вики/таски — сущности сервиса через `using-wiki` / `using-tasks`; файловый layout — легаси); if a project has neither, Rule 1 simply finds no overrides and falls back to skill defaults. - -## Why this exists - -In a tightly-disciplined repo (`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 falls back to vendor-default paths (`docs/specs/`, `docs/plans/`), 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 `AGENTS.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 `skills`).