feat(hermes): MVP converter + 4 universal skills converted
Adds the conversion infrastructure for the Hermes-rollout (Nous Research): - hermes/mapping.yaml — per-skill schema (mode: auto|manual|skip|pending, category, replace-rules, source override). Every skills/<name>/ has an explicit entry; the build fails on unmapped skills. - scripts/build-hermes.py — Python converter. Reads mapping.yaml; for auto applies replace-rules to SKILL.md and copies the rest verbatim; for manual copies hermes/skills/<source>/ as-is; for skip / pending records to dist-hermes/SKIPPED.md. - dist-hermes/ — pre-converted Hermes-flavour tree (committed; consumed by the recursive installer in [hermes-installer-skill]). Includes 4 universal skills: pulling-before-work, active-platform (with Linux+bash replacement rule), project-discipline, using-markitdown. Plus SKIPPED.md listing 8 skip + 10 pending entries. - README.md — adds "Build for Hermes" section, updates layout, mentions hermes/, dist-hermes/, build-hermes.py. Mapping is the source of truth for the audit table from .wiki/concepts/hermes-skills-rollout-design.md (Q1-Q8). Pending entries preserve the audit decision (intended mode/category) for the follow-up tasks: hermes-flavour-mcp-setups, hermes-installer-skill, hermes-mvp-coverage. Security carry-forward (extraheader-pattern, POSIX-absolute paths, semver bumps) — infrastructure ready (replace-rules + manual mode); concrete content lands in hermes-flavour-mcp-setups. Smoke-tests: idempotent re-run produces no diff; replace-rules verified on active-platform (Linux+bash); strict-mapping fail-fast verified on a synthetic unmapped skill (exit 1). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
139
dist-hermes/software-development/project-discipline/SKILL.md
Normal file
139
dist-hermes/software-development/project-discipline/SKILL.md
Normal file
@@ -0,0 +1,139 @@
|
||||
---
|
||||
name: project-discipline
|
||||
version: 0.1.1
|
||||
description: >
|
||||
Codifies five cross-project discipline rules: (1) project CLAUDE.md /
|
||||
.wiki/CLAUDE.md / .tasks/ override defaults from any other skill (specs
|
||||
go to .wiki/concepts/, not docs/superpowers/specs/; tasks to .tasks/,
|
||||
not docs/superpowers/plans/); (2) all work on master/main, no feature
|
||||
branches without explicit user approval; (3) bump semver on every edit
|
||||
of versioned artifacts (SKILL.md frontmatter, package.json,
|
||||
pyproject.toml) per MAJOR/MINOR/PATCH rules, recorded in commit message;
|
||||
(4) commit freely, never push without explicit per-session user approval
|
||||
— grant via "разреши автопуш" / "allow auto-push", revoke via "отзови"
|
||||
/ "revoke", session end resets to ask-mode; force/delete/non-ff push
|
||||
always asks; (5) transit-zone / brainstorm workspaces — artifacts
|
||||
go to .brainstorm/ or global wiki only via explicit user direction,
|
||||
never auto-promote by analogy. Activated by "follow project discipline"
|
||||
trigger in CLAUDE.md (added by project-bootstrap v1.5.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 `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/<topic>-design.md`, **not** `docs/superpowers/specs/`.
|
||||
- **Task tracking / implementation plans** go to `.tasks/<slug>.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(<artifact>): … [vX.Y.Z]` or whatever convention the project uses (see Rule 1).
|
||||
|
||||
**Applies to:** `skills/<name>/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/<name>.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'нуть в `<remote>/<branch>` (N коммитов: <subjects>). Ок?
|
||||
|
||||
(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>` (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.
|
||||
|
||||
## 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/<topic>.md` (or whatever the workspace's README/CLAUDE.md declares)
|
||||
- **Mature, cross-cutting outputs** → `~/projects/.wiki/concepts/<topic>-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 CLAUDE.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 `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`).
|
||||
Reference in New Issue
Block a user