feat(skills): update setup-projects-meta paths for .common/lib/
- Replace ~/.local/projects-meta-mcp → ~/projects/.common/lib/projects-meta-mcp - Update setup-projects-meta and using-projects-meta skills - Rebuild dist/ with new paths Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
120
.tasks/STATUS.md
120
.tasks/STATUS.md
@@ -1,38 +1,6 @@
|
|||||||
# Task Board
|
# Task Board
|
||||||
_Updated: 2026-05-05_
|
_Updated: 2026-05-05_
|
||||||
|
|
||||||
## 🟢 [shared-wiki-skill-catalog] — публикация каталога claude-skills в shared projects-wiki
|
|
||||||
**Status:** done
|
|
||||||
**Where I stopped:** `packages/claude-skills` опубликован в `projects-wiki` через `knowledge_ingest` (3 коммита Gitea: ae2cc9a3 page + 14bdd863 index + 001cdd0e log); каталог всех 20 скиллов сгруппирован: bootstrap & discipline / wiki+tasks / MCP integrations / caveman cluster / discovery+platform; cross-link с `concepts/setup-using-skill-pair` (паттерн setup-X/using-X) и `packages/projects-meta-mcp`; local `~/projects/projects-wiki/` подтянут ff-only до `001cdd0e`; запись в local `.wiki/log.md` добавлена
|
|
||||||
**Next action:** (none — kept until merged)
|
|
||||||
**Branch:** master
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🟢 [project-discipline-skill] — project-discipline skill + project-bootstrap 1.5.0 canonical trigger
|
|
||||||
**Status:** done
|
|
||||||
**Where I stopped:** `skills/project-discipline/` shipped at v0.1.0 (four rules: convention-override, master-only, semver-bumping with first-edit-unversioned clause, session-scoped ask-before-push with grant/revoke and force/delete/non-ff exceptions); `assets/CLAUDE.md.template` gains `follow project discipline` after `pull remote before work`; `project-bootstrap` 1.4.0→1.5.0 with new commentary paragraph in Step 5 + manifest table row in Step 5.5; `.wiki/concepts/skill-versioning.md` extended (Rule 3 expands `version:` requirement to ALL skills, not just infra subset); root `CLAUDE.md` dogfood line added; both archives rebuilt in `dist/`; installed via `install.sh`; description length verified 855 chars (≤900); smoke scenarios 1 (skill listing with full description, not H1 fallback) + 9 (length regression check) verified inline post-install; scenarios 2-8 (Rule 1-4 in fresh sessions, bootstrap upgrade) deferred — require multi-session orchestration; design rationale at `.wiki/concepts/project-discipline-design.md`
|
|
||||||
**Next action:** (none — kept until merged)
|
|
||||||
**Branch:** master
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🟢 [pulling-before-work-skill] — pulling-before-work skill + project-bootstrap 1.4.0 canonical trigger
|
|
||||||
**Status:** done
|
|
||||||
**Where I stopped:** `skills/pulling-before-work/` shipped at v1.0.0 (mode-3 activation: session start + on-demand re-sync; `git pull --ff-only`; skips on no-remote / no-upstream / dirty / detached); `assets/CLAUDE.md.template` gains `pull remote before work`; `project-bootstrap` 1.3.0→1.4.0 with new commentary paragraph in Step 5; root `CLAUDE.md` dogfood line added; both archives rebuilt in `dist/`; installed via `install.sh`; smoke scenarios 1/2/3/4/5/8/9 + inline bootstrap-merge check verified by controller, scenarios 6 (diverged remote) and 7 (re-sync trigger across a fresh session) deferred — both require multi-session orchestration not yet tooled; design rationale at `.wiki/concepts/pulling-before-work-design.md`
|
|
||||||
**Next action:** (none — kept until merged)
|
|
||||||
**Branch:** master
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🟢 [bootstrap-claude-md-merge] — project-bootstrap upgrade: idempotent merge of canonical CLAUDE.md triggers
|
|
||||||
**Status:** done
|
|
||||||
**Where I stopped:** Step 5 in `skills/project-bootstrap/SKILL.md` split into Init / Upgrade-merge — upgrade reads existing CLAUDE.md, substring-diffs vs template (case-insensitive trim), platform line preserved if user pinned a non-host platform, asks confirm with diff, appends only missing canonical lines; version bump 1.2.0 → 1.3.0; skill row in `skills/project-bootstrap/README.md` updated to note idempotent merge; root `README.md` + `README.ru.md` upgrade-mode paragraph extended; reinstalled to `~/.claude/skills/project-bootstrap/`, `dist/project-bootstrap.skill` rebuilt; concept page `.wiki/concepts/bootstrap-claude-md-merge.md` written; index + log entries added
|
|
||||||
**Next action:** (none — kept until merged)
|
|
||||||
**Branch:** master
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
<!--
|
<!--
|
||||||
Canonical layout. One block per task. Per-task deep context lives in
|
Canonical layout. One block per task. Per-task deep context lives in
|
||||||
.tasks/<task-slug>.md (created by using-tasks when a task becomes active
|
.tasks/<task-slug>.md (created by using-tasks when a task becomes active
|
||||||
@@ -46,30 +14,6 @@ _Updated: 2026-05-05_
|
|||||||
🔵 Blocked — waiting on external input
|
🔵 Blocked — waiting on external input
|
||||||
-->
|
-->
|
||||||
|
|
||||||
## 🟢 [bootstrap-projects-meta-trigger] — project-bootstrap CLAUDE.md template gains `check across all projects`
|
|
||||||
**Status:** done
|
|
||||||
**Where I stopped:** template + inline SKILL.md copy patched, version bumped 1.1.0→1.2.0; both READMEs and local CLAUDE.md synced; skill reinstalled to `~/.claude/skills/project-bootstrap/`, `dist/project-bootstrap.skill` rebuilt; concept extension added to `.wiki/concepts/projects-meta-skills.md`; log entry written; verified installed `version: 1.2.0` and template carries the new line
|
|
||||||
**Next action:** (none — kept until merged)
|
|
||||||
**Branch:** master
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🟢 [bootstrap-recommend-superpowers] — project-bootstrap recommends superpowers plugin if missing
|
|
||||||
**Status:** done
|
|
||||||
**Where I stopped:** Step 5.6 added to `skills/project-bootstrap/SKILL.md` (read `~/.claude/plugins/installed_plugins.json`, print install command + upstream link if `superpowers@claude-plugins-official` key missing); version bumped 1.0.0 → 1.1.0; README workflow numbering updated; skill reinstalled to `~/.claude/skills/project-bootstrap/` and `dist/project-bootstrap.skill` rebuilt; log entry added
|
|
||||||
**Next action:** (none — kept until merged)
|
|
||||||
**Branch:** master
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🟢 [mac-support-scripts] — fix install.sh / build.sh for stock macOS
|
|
||||||
**Status:** done
|
|
||||||
**Where I stopped:** patched both scripts to drop `mapfile` (bash 4+) and `find -printf` (GNU find) — replaced with portable shell glob + `basename` + `sort`; verified on git-bash (16 skills discovered, install dry-run + build smoke-test passed); wiki concept page `install-portability.md` added; index + log updated
|
|
||||||
**Next action:** (none — kept until merged)
|
|
||||||
**Branch:** master
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🟡 [skill-readmes] — write English README.md for every skill + translate root README
|
## 🟡 [skill-readmes] — write English README.md for every skill + translate root README
|
||||||
**Status:** paused
|
**Status:** paused
|
||||||
**Where I stopped:** infra-skill cluster done — READMEs for `project-bootstrap`, `setup-wiki`, `setup-tasks`, `using-wiki`, `using-tasks`; root README translated; cross-links between all five skills wired up
|
**Where I stopped:** infra-skill cluster done — READMEs for `project-bootstrap`, `setup-wiki`, `setup-tasks`, `using-wiki`, `using-tasks`; root README translated; cross-links between all five skills wired up
|
||||||
@@ -78,6 +22,23 @@ _Updated: 2026-05-05_
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## ⚪ [bootstrap-skill-deps-check] — refactor project-bootstrap Step 5.6 into a generic skill-dependencies check (replaces per-skill `Step 5.X` mirror shape)
|
||||||
|
**Status:** ready
|
||||||
|
**Where I stopped:** (not started) — design agreed in chat 2026-05-05 after `[interns-skills-mvp]` shipped: adding `delegate to interns when allowed` to the canonical CLAUDE.md template made it visible that every new trigger would need its own `Step 5.X` detector mirror, which doesn't scale. Decision: collapse Step 5.6 (superpowers plugin) and the deferred `[bootstrap-recommend-projects-meta]` into a single generic `Step 5.6` that reads the canonical trigger list and maps each line to a fulfiller (skill or plugin) for missing-deps detection. Hard rule "never auto-install" carries over verbatim — chat-only recommendation block with copy-pasteable install commands
|
||||||
|
**Next action:** Read `.tasks/bootstrap-skill-deps-check.md` for the full spec — initial trigger→fulfiller seed table is in the Notes section. Write `.wiki/concepts/bootstrap-skill-deps-check.md` design page first (rationale: why generic over per-skill mirrors, kind: skill vs plugin distinction, MCP server caveat). Then edit `skills/project-bootstrap/SKILL.md` Step 5.6 in place, bump `version:` 1.6.0 → 1.7.0. Update `skills/project-bootstrap/README.md` Workflow Step 5.6 description. Rebuild + install. Close `[bootstrap-recommend-projects-meta]` with a note in commit message
|
||||||
|
**Branch:** (not started)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⚪ [bootstrap-recommend-projects-meta] — Step 5.7 in project-bootstrap: recommend `setup-projects-meta` if MCP tools missing
|
||||||
|
**Status:** superseded
|
||||||
|
**Where I stopped:** (not started) — opened as follow-up to `[bootstrap-projects-meta-trigger]`. The `check across all projects` trigger is now in every CLAUDE.md template, but on a fresh machine without `projects-meta-mcp` registered the trigger is silently no-op until the user verbally asks for cross-project work
|
||||||
|
**Next action:** **superseded by `[bootstrap-skill-deps-check]`** (2026-05-05) — that task absorbs this one into a generic `Step 5.6` that walks the whole canonical trigger list, not just projects-meta. Kept here for git-log archaeology; close once `[bootstrap-skill-deps-check]` ships
|
||||||
|
**Branch:** (not started)
|
||||||
|
**Blocker:** waits on observing a real fresh-machine bootstrap that silently misses the dependency — defer until we see the failure mode in practice
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## ⚪ [compress-dedup] — resolve compress vs caveman-compress duplication
|
## ⚪ [compress-dedup] — resolve compress vs caveman-compress duplication
|
||||||
**Status:** ready
|
**Status:** ready
|
||||||
**Where I stopped:** (not started) — noticed during initial migration that both skills ship identical `scripts/` subtrees (`compress.py`, `cli.py`, `detect.py`, `validate.py`, `benchmark.py`)
|
**Where I stopped:** (not started) — noticed during initial migration that both skills ship identical `scripts/` subtrees (`compress.py`, `cli.py`, `detect.py`, `validate.py`, `benchmark.py`)
|
||||||
@@ -127,44 +88,7 @@ _Updated: 2026-05-05_
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## ⚪ [bootstrap-recommend-projects-meta] — Step 5.7 in project-bootstrap: recommend `setup-projects-meta` if MCP tools missing
|
|
||||||
**Status:** superseded
|
|
||||||
**Where I stopped:** (not started) — opened as follow-up to `[bootstrap-projects-meta-trigger]` (commit b120397). The `check across all projects` trigger is now in every CLAUDE.md template, but on a fresh machine without `projects-meta-mcp` registered the trigger is silently no-op until the user verbally asks for cross-project work
|
|
||||||
**Next action:** **superseded by `[bootstrap-skill-deps-check]`** (2026-05-05) — that task absorbs this one into a generic `Step 5.6` that walks the whole canonical trigger list, not just projects-meta. Kept here for git-log archaeology; close once `[bootstrap-skill-deps-check]` ships
|
|
||||||
**Branch:** (not started)
|
|
||||||
**Blocker:** waits on observing a real fresh-machine bootstrap that silently misses the dependency — defer until we see the failure mode in practice
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ⚪ [bootstrap-skill-deps-check] — refactor project-bootstrap Step 5.6 into a generic skill-dependencies check (replaces per-skill `Step 5.X` mirror shape)
|
|
||||||
|
|
||||||
**Status:** ready
|
|
||||||
**Where I stopped:** (not started) — design agreed in chat 2026-05-05 after `[interns-skills-mvp]` shipped: adding `delegate to interns when allowed` to the canonical CLAUDE.md template made it visible that every new trigger would need its own `Step 5.X` detector mirror, which doesn't scale. Decision: collapse Step 5.6 (superpowers plugin) and the deferred `[bootstrap-recommend-projects-meta]` into a single generic `Step 5.6` that reads the canonical trigger list and maps each line to a fulfiller (skill or plugin) for missing-deps detection. Hard rule "never auto-install" carries over verbatim — chat-only recommendation block with copy-pasteable install commands
|
|
||||||
**Next action:** Read `.tasks/bootstrap-skill-deps-check.md` for the full spec — initial trigger→fulfiller seed table is in the Notes section. Write `.wiki/concepts/bootstrap-skill-deps-check.md` design page first (rationale: why generic over per-skill mirrors, kind: skill vs plugin distinction, MCP server caveat). Then edit `skills/project-bootstrap/SKILL.md` Step 5.6 in place, bump `version:` 1.6.0 → 1.7.0. Update `skills/project-bootstrap/README.md` Workflow Step 5.6 description. Rebuild + install. Close `[bootstrap-recommend-projects-meta]` with a note in commit message
|
|
||||||
**Branch:** (not started)
|
|
||||||
|
|
||||||
## 🟢 [using-projects-meta-freshness-gate] — добавить Step 0 freshness check в using-projects-meta
|
|
||||||
|
|
||||||
**Status:** done
|
|
||||||
**Where I stopped:** Step 0 добавлен в `using-projects-meta/SKILL.md` (cache_age>10мин или errors>0 → `dist/sync.js` для read; shared-wiki write — безусловный `git pull --ff-only`; 401/403 → auth.toml rotation); зеркалирован в README; bump 1.0.0→1.1.0; rebuild+install OK; description trimmed до 924 chars после регрессии (полное Step 0 в description ~1450 chars сломало парсинг — harness зафолбэкнулся на H1, скилл потерял все триггеры); Common mistakes + Red flags расширены; concept page + log обновлены; new feedback memory `skill_description_length_limit`
|
|
||||||
**Next action:** (none — kept until merged)
|
|
||||||
**Branch:** master
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🟢 [projects-meta-skills] — setup-projects-meta + using-projects-meta — пара скиллов для projects-meta-mcp
|
|
||||||
|
|
||||||
**Status:** done
|
|
||||||
**Where I stopped:** оба скилла v1.0.0 написаны (8-phase setup + using policy с local-first и two-step mutation), README обоим, собраны в `dist/`, установлены в `~/.claude/skills/`, видны в `Skill` tool listing; concept-страница `projects-meta-skills.md` добавлена в `.wiki/`; path-canon `~/projects/projects-wiki/` починен в скиллах после wiki-path-mismatch fix (upstream commit 621a69f); якоря MCP подтянулись после ручного pull
|
|
||||||
**Next action:** (none — kept until merged); требуется restart Claude Code чтобы новые скиллы стали активными в новой сессии (build/install уже сделаны)
|
|
||||||
**Branch:** master
|
|
||||||
<!-- created-by: OpeItcLoc03@DESKTOP-NSEF0UK / from: projects-meta-mcp / 2026-04-29T20:28:04.101Z -->
|
|
||||||
<!-- closed-by: OpeItcLoc03@DESKTOP-NSEF0UK / 2026-04-29T21:26:01.923Z / note: setup-projects-meta + using-projects-meta v1.0.0 shipped; path-canon ~/projects/projects-wiki/ fixed after wiki-path-mismatch resolution -->
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ⚪ [refresh-project-bootstrap] — Run the `project-bootstrap` skill in this repo to refresh its layout to the canonical state (git, .gitignore, README.md, .wiki/, .tasks/, CLAUDE.md). The skill handles both greenfield bootstrap and refresh of existing repos.
|
## ⚪ [refresh-project-bootstrap] — Run the `project-bootstrap` skill in this repo to refresh its layout to the canonical state (git, .gitignore, README.md, .wiki/, .tasks/, CLAUDE.md). The skill handles both greenfield bootstrap and refresh of existing repos.
|
||||||
|
|
||||||
**Status:** ready
|
**Status:** ready
|
||||||
**Where I stopped:** (not started)
|
**Where I stopped:** (not started)
|
||||||
**Next action:** Invoke the `project-bootstrap` skill at the repo root, confirm each file write, push to main.
|
**Next action:** Invoke the `project-bootstrap` skill at the repo root, confirm each file write, push to main.
|
||||||
@@ -172,13 +96,3 @@ _Updated: 2026-05-05_
|
|||||||
<!-- created-by: OpeItcLoc03@DESKTOP-NSEF0UK / from: projects-meta-mcp / 2026-05-01T09:03:49.873Z -->
|
<!-- created-by: OpeItcLoc03@DESKTOP-NSEF0UK / from: projects-meta-mcp / 2026-05-01T09:03:49.873Z -->
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🟢 [interns-skills-mvp] — Ship `setup-interns` + `using-interns` skills (v0.1.0) and bump `project-bootstrap` 1.5.0 → 1.6.0 with `delegate to interns when allowed` CLAUDE.md trigger, manifest entry, Step 5 commentary paragraph, idempotent merge into existing CLAUDE.md files. Two-skill pair following the setup-X / using-X prior art (setup-context7/using-context7, setup-projects-meta/using-projects-meta). Per-session permission grant policy mirroring project-discipline Rule 4 (ask-mode default, conversational grant/revoke, always-ask paths for secrets even with active grant, session-end reset).
|
|
||||||
|
|
||||||
**Status:** done
|
|
||||||
**Where I stopped:** `skills/setup-interns/` v0.1.0 shipped (8-phase install: detect `.common/lib/interns-mcp/` source, `pip install -e`, write `.common/secrets/interns.env` with endpoint API keys + ensure `.gitignore` covers it, register `mcpServers.interns` in `~/.claude.json` with absolute Python interpreter path + `cwd` to project root); `skills/using-interns/` v0.1.0 shipped (runtime policy mirroring project-discipline Rule 4: ask-mode default, conversational grant/revoke, always-ask paths for `.env` / `**/secrets/**` / `**/*.key` / `**/.ssh/**` / `**/.aws/credentials` etc with transitive rule + cost-cap >$0.10, session-end reset; routing hints for `bulk_text_read` + `transcript_distill`); `project-bootstrap` 1.5.0→1.6.0 with canonical CLAUDE.md trigger `delegate to interns when allowed` inserted between `follow project discipline` and `we're on Windows`, new Step 5 commentary paragraph, Step 5.5 manifest table extended with `setup-interns` + `using-interns` + `project-discipline` rows; root `CLAUDE.md` dogfood line added; both READMEs written; descriptions verified within budget (setup-interns 899 / using-interns 814 / ≤900); both archives rebuilt + installed; harness listing confirms full descriptions (no H1 fallback) for all three skills
|
|
||||||
**Next action:** (none — kept until merged)
|
|
||||||
**Branch:** master
|
|
||||||
<!-- created-by: OpeItcLoc03@DESKTOP-NSEF0UK / from: meeting-room / 2026-05-05T13:59:07.540Z -->
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|||||||
@@ -1,53 +0,0 @@
|
|||||||
# bootstrap-claude-md-merge
|
|
||||||
|
|
||||||
## Goal
|
|
||||||
project-bootstrap upgrade mode currently treats `CLAUDE.md` as binary: either append
|
|
||||||
the entire template (causing duplicate trigger lines) or leave it untouched. Result:
|
|
||||||
projects bootstrapped before v1.2.0 silently miss new canonical triggers like
|
|
||||||
`check across all projects` (→ `using-projects-meta`) and `we're on Windows`
|
|
||||||
(→ `active-platform`) when re-run on the upgrade path. Fix: turn Step 5 into an
|
|
||||||
idempotent merge — read existing CLAUDE.md, diff against the template, append only
|
|
||||||
missing canonical lines after user confirm. Re-runs become no-ops.
|
|
||||||
|
|
||||||
## Key files
|
|
||||||
- `skills/project-bootstrap/SKILL.md:220-249` — Step 5 (the broken binary choice)
|
|
||||||
- `skills/project-bootstrap/assets/CLAUDE.md.template` — canonical trigger set
|
|
||||||
- `skills/project-bootstrap/README.md` — public surface, mention idempotency
|
|
||||||
- `dist/project-bootstrap.skill` — rebuild after install
|
|
||||||
- `~/.claude/skills/project-bootstrap/` — reinstall target
|
|
||||||
|
|
||||||
## Decisions log
|
|
||||||
- 2026-04-30: Diff strategy — substring match per template line against existing file
|
|
||||||
(trim + lowercase). A trigger is "present" if any existing line contains the template
|
|
||||||
trigger text. Avoids false-positive duplicates when user has rephrased a trigger but
|
|
||||||
preserves canonical wording for missing ones. Rejected: full line-equality match
|
|
||||||
(too brittle — user comments / case differences would re-add).
|
|
||||||
- 2026-04-30: Confirmation gate stays — show user the diff (N lines to append) before
|
|
||||||
touching the file. Idempotent run with no missing lines = silent no-op.
|
|
||||||
- 2026-04-30: Version bump 1.2.0 → 1.3.0. Behavior change visible to users on every
|
|
||||||
upgrade — minor bump fits semver intent.
|
|
||||||
|
|
||||||
## Open questions
|
|
||||||
- [ ] Should the platform line (`we're on Windows`) be substituted to match the host
|
|
||||||
during merge, the same way init does it? Decision: yes — if existing file has no
|
|
||||||
`we're on (Windows|Linux|macOS)` line, append the host-appropriate one. If it has
|
|
||||||
any of the three, leave it (user may have intentionally pinned a different platform).
|
|
||||||
|
|
||||||
## Completed steps
|
|
||||||
- [x] open task
|
|
||||||
- [x] patch Step 5 in SKILL.md (read → diff → confirm → append) — split Init / Upgrade-merge
|
|
||||||
- [x] bump version 1.2.0 → 1.3.0 in SKILL.md frontmatter
|
|
||||||
- [x] update `skills/project-bootstrap/README.md` `CLAUDE.md` row to note idempotent merge
|
|
||||||
- [x] update root `README.md` + `README.ru.md` upgrade-mode paragraph
|
|
||||||
- [x] reinstall + rebuild dist (`bash scripts/install.sh project-bootstrap && bash scripts/build.sh project-bootstrap`); verified `version: 1.3.0` on disk + Step 5 split
|
|
||||||
- [x] wiki: concept page `.wiki/concepts/bootstrap-claude-md-merge.md`, index entry, log entry
|
|
||||||
- [x] commit
|
|
||||||
- [x] STATUS.md: 🔴 → 🟢
|
|
||||||
- [x] decision on platform line — preserve if user pinned non-host one (case-insensitive `we're on (windows|linux|macos)` match)
|
|
||||||
|
|
||||||
## Notes
|
|
||||||
Existing related task `[bootstrap-recommend-projects-meta]` (Step 5.7) is **machine-level**
|
|
||||||
detection (recommend `setup-projects-meta` if MCP server not registered). This task is
|
|
||||||
**project-level** merge of the trigger line into the project's CLAUDE.md. They compose
|
|
||||||
cleanly: 5.7 makes the trigger functional on the host, this task ensures the trigger
|
|
||||||
is actually present in the file.
|
|
||||||
@@ -1,30 +0,0 @@
|
|||||||
# bootstrap-projects-meta-trigger
|
|
||||||
|
|
||||||
## Goal
|
|
||||||
Add `check across all projects` to the CLAUDE.md template that `project-bootstrap` writes to every project, so the `using-projects-meta` skill auto-loads in every bootstrapped repo (current set already had four triggers — `talk like a caveman`, `use superpowers`, `use project wiki`, `use task management system`, plus `we're on Windows`). Bumps `project-bootstrap` 1.1.0 → 1.2.0 (additive default-artifact change).
|
|
||||||
|
|
||||||
## Key files
|
|
||||||
- `skills/project-bootstrap/assets/CLAUDE.md.template` — the file actually copied into bootstrapped projects
|
|
||||||
- `skills/project-bootstrap/SKILL.md` — inline copy of the same template (must stay in sync) + version frontmatter
|
|
||||||
- `README.md` / `README.ru.md` — the "Using skills in projects" section enumerates the trigger list
|
|
||||||
- `CLAUDE.md` (this repo) — local instance must also gain the line so the trigger fires here too
|
|
||||||
- `dist/project-bootstrap.skill` — packaged artifact, rebuilt from the source tree
|
|
||||||
|
|
||||||
## Decisions log
|
|
||||||
- 2026-04-30: trigger phrase = `check across all projects` — buffer-direct quote from `using-projects-meta` description, matches existing imperative style of other lines (`use X`, `talk like X`).
|
|
||||||
- 2026-04-30: not adding a Step 5.7 mirror of Step 5.6 (recommend `setup-projects-meta`) — out of scope for this task. Trigger fires `using-projects-meta` whose Prerequisites already point at `setup-projects-meta` if MCP tools are missing. Open question for follow-up.
|
|
||||||
|
|
||||||
## Open questions
|
|
||||||
- [ ] Should `project-bootstrap` also detect missing `mcp__projects-meta__*` tools and recommend `setup-projects-meta` (analogous to Step 5.6 for superpowers)? Defer until we see a fresh-machine bootstrap miss the dependency.
|
|
||||||
|
|
||||||
## Completed steps
|
|
||||||
- [x] task entry created
|
|
||||||
- [x] `skills/project-bootstrap/assets/CLAUDE.md.template` — added `check across all projects` between `use task management system` and `we're on Windows`
|
|
||||||
- [x] `skills/project-bootstrap/SKILL.md` — inline template at Step 5 synced; explanatory paragraph added; `version: 1.1.0 → 1.2.0`
|
|
||||||
- [x] `README.md` + `README.ru.md` — trigger list in "Using skills in projects" / "Использование в проектах" updated
|
|
||||||
- [x] `CLAUDE.md` (this repo) — local instance gained the new line so the trigger fires here
|
|
||||||
- [x] `bash scripts/install.sh project-bootstrap` — reinstalled to `~/.claude/skills/project-bootstrap/`
|
|
||||||
- [x] `bash scripts/build.sh project-bootstrap` — `dist/project-bootstrap.skill` rebuilt
|
|
||||||
- [x] verified: installed `version: 1.2.0`, template content matches
|
|
||||||
- [x] `.wiki/concepts/projects-meta-skills.md` — appended "Bootstrap trigger (project-bootstrap@1.2.0)" section explaining choice of phrase + non-decision on Step 5.7
|
|
||||||
- [x] `.wiki/log.md` — `decision` entry added
|
|
||||||
@@ -1,34 +0,0 @@
|
|||||||
# bootstrap-recommend-superpowers
|
|
||||||
|
|
||||||
## Goal
|
|
||||||
`project-bootstrap` writes `use superpowers` into the new project's `CLAUDE.md` (Step 5 template), but that trigger only fires if the `superpowers@claude-plugins-official` plugin is installed. On a fresh machine the plugin is often absent, so the trigger silently no-ops. Add a Step 5.6 that detects the plugin via `~/.claude/plugins/installed_plugins.json` and, when missing, prints a recommendation with the exact install command + upstream link. Strictly informational — never auto-installs.
|
|
||||||
|
|
||||||
## Key files
|
|
||||||
- `skills/project-bootstrap/SKILL.md` — add Step 5.6 between 5.5 (manifest) and 6 (commit); bump frontmatter `version: 1.0.0 → 1.1.0`
|
|
||||||
- `skills/project-bootstrap/README.md` — extend the steps overview to mention the new check
|
|
||||||
- `~/.claude/plugins/installed_plugins.json` — detection source
|
|
||||||
|
|
||||||
## Decisions log
|
|
||||||
- 2026-04-28: Place check at Step 5.6 (right after manifest, before commit). Reason: CLAUDE.md just got `use superpowers`, so the recommendation lands while context is fresh. Alternative — fold into Step 0 detect — rejected: Step 0 is meant to be quick + read-only summary; threading plugin checks there bloats the no-op happy path.
|
|
||||||
- 2026-04-28: Detection by file read, not by `/plugin list`. Reason: slash commands aren't callable from inside a skill; the JSON file is the source of truth Claude Code itself reads. Same approach as `setup-context7` Phase 1.
|
|
||||||
- 2026-04-28: Recommendation, not auto-install. Reason: `/plugin install` is interactive and per `setup-context7` we can't drive slash commands from a skill. Even if we could, auto-installing a plugin without consent is overreach.
|
|
||||||
- 2026-04-28: Limit scope to `superpowers` only. User explicitly asked for that one. Generic "recommended plugins" framework is feature creep — defer until there's a second item.
|
|
||||||
|
|
||||||
## Open questions
|
|
||||||
- [ ] None — done.
|
|
||||||
|
|
||||||
## Completed steps
|
|
||||||
- [x] Confirm plugin install path / JSON shape from local `installed_plugins.json`
|
|
||||||
- [x] Pick insertion point (Step 5.6)
|
|
||||||
- [x] Pick detection method (file read of `installed_plugins.json`)
|
|
||||||
- [x] Patch `SKILL.md` (Step 5.6 + frontmatter `version: 1.1.0`)
|
|
||||||
- [x] Update `README.md` workflow numbering
|
|
||||||
- [x] Reinstall to `~/.claude/skills/project-bootstrap/`
|
|
||||||
- [x] Rebuild `dist/project-bootstrap.skill`
|
|
||||||
- [x] Append wiki log entry
|
|
||||||
- [x] Commit
|
|
||||||
|
|
||||||
## Notes
|
|
||||||
- Plugin install command (canonical, from `installed_plugins.json` key): `/plugin install superpowers@claude-plugins-official`
|
|
||||||
- Upstream: https://github.com/anthropics/claude-plugins-official
|
|
||||||
- Cross-platform path: `~/.claude/plugins/installed_plugins.json` resolves identically on Windows / Linux / macOS.
|
|
||||||
@@ -1,38 +0,0 @@
|
|||||||
# interns-skills-mvp
|
|
||||||
|
|
||||||
## Goal
|
|
||||||
Ship the first version of the `setup-interns` + `using-interns` skill pair (v0.1.0 each) and roll the canonical `delegate to interns when allowed` CLAUDE.md trigger into `project-bootstrap` (1.5.0 → 1.6.0). The pair exposes the local `interns` MCP server (Layer 2 of `.wiki/concepts/interns-design.md`) to Claude Code under a per-session permission grant that mirrors `project-discipline` Rule 4 — ask-mode by default, conversational grant/revoke, always-ask paths for secrets even with an active grant, session-end reset. The runtime server itself is out of scope for this task; the skills land their full lifecycle (install procedure, runtime policy, bootstrap integration) so that on every machine where the MCP server is later installed, Claude already knows the policy.
|
|
||||||
|
|
||||||
## Key files
|
|
||||||
- `.wiki/concepts/interns-design.md` — Layer 3 Skills section is the primary spec
|
|
||||||
- `skills/setup-interns/SKILL.md` — to be created (mirror `skills/setup-projects-meta/SKILL.md` 8-phase shape)
|
|
||||||
- `skills/setup-interns/README.md` — to be created (mirror `skills/setup-projects-meta/README.md`)
|
|
||||||
- `skills/using-interns/SKILL.md` — to be created (mirror `skills/using-projects-meta/SKILL.md` two-class shape; grant mechanism mirrors `skills/project-discipline/SKILL.md` Rule 4)
|
|
||||||
- `skills/using-interns/README.md` — to be created
|
|
||||||
- `skills/project-bootstrap/SKILL.md` — Step 5 commentary + Step 5.5 manifest table; bump `version:` 1.5.0 → 1.6.0
|
|
||||||
- `skills/project-bootstrap/assets/CLAUDE.md.template` — append `delegate to interns when allowed` between `follow project discipline` and `we're on Windows`
|
|
||||||
- `CLAUDE.md` (root, dogfood) — same line addition
|
|
||||||
- `.wiki/log.md` — `## [2026-05-05] decision | interns-skills-mvp shipped` entry
|
|
||||||
- `dist/setup-interns.skill`, `dist/using-interns.skill`, `dist/project-bootstrap.skill` — rebuilt archives
|
|
||||||
|
|
||||||
## Decisions log
|
|
||||||
- 2026-05-05: ship as a pair (setup-X + using-X) following the validated prior-art pattern — same shape as setup-context7/using-context7 and setup-projects-meta/using-projects-meta. Rationale: clean separation of one-time install (mutates user-level config; needs confirmation gates) from runtime policy (read every session; no mutations). Cross-reference between the two via the `Prerequisites` section.
|
|
||||||
- 2026-05-05: setup-interns assumes inline `.common/lib/interns-mcp/` layout per design's "current склонение". Open question (Gitea repo + subtree) deferred — v0.1.0 documents the inline path; if a separate repo lands later, a 0.2.0 minor adds the alternate clone branch.
|
|
||||||
- 2026-05-05: grant mechanism mirrors project-discipline Rule 4 verbatim — ask-mode default per session, conversational grant ("разреши интернов" / "allow interns"), conversational revoke, always-ask paths even under an active grant, session-end automatic reset. Rationale: same security posture, same UX vocabulary the user already trained on.
|
|
||||||
- 2026-05-05: always-ask path list copied from design Layer 3 verbatim plus the transitive rule (Claude reading a matched file and forwarding content also triggers the gate). Plus cost-based ask: any call with estimated cost > $0.10 (sanity bound).
|
|
||||||
- 2026-05-05: `description:` budget — keep ≤ 900 chars per `feedback_skill_description_length_limit` memory. Verify char count before shipping; if over, trim trigger phrases first, never the policy summary.
|
|
||||||
|
|
||||||
## Open questions
|
|
||||||
- [ ] How does the user's actual `.common/` layout look on disk? Setup skill currently assumes `<project-root>/.common/lib/interns-mcp/` and `<project-root>/.common/secrets/interns.env`. If the convention is `~/projects/.common/`, the discovery phase needs to widen.
|
|
||||||
- [ ] Should `setup-interns` ship a scaffolding sub-step that writes a placeholder `.common/lib/interns-mcp/` from a template if the source isn't there? Probably not — kicks the can to a separate "build the runtime" task.
|
|
||||||
|
|
||||||
## Completed steps
|
|
||||||
- [x] Read design `.wiki/concepts/interns-design.md` Layer 3 section
|
|
||||||
- [x] Survey prior art: setup-context7, setup-projects-meta, using-context7, using-projects-meta, project-bootstrap@1.5.0, project-discipline (Rule 4 grant mechanism)
|
|
||||||
- [x] Mark 🔴 active in `.tasks/STATUS.md`, create this file
|
|
||||||
|
|
||||||
## Notes
|
|
||||||
- Char-count check after writing each `description:` — paste into a quick `wc -c` PowerShell snippet (or count manually). 1024 is the hard ceiling, 900 is the safety margin.
|
|
||||||
- Restart-Claude-Code caveat goes in setup-interns Phase 8, identical to setup-projects-meta and setup-context7.
|
|
||||||
- `using-interns` does NOT mention restart — it's a policy skill, no MCP install side.
|
|
||||||
- Bootstrap-manifest table gets `setup-interns` and `using-interns` rows.
|
|
||||||
@@ -1,31 +0,0 @@
|
|||||||
# mac-support-scripts
|
|
||||||
|
|
||||||
## Goal
|
|
||||||
Make `scripts/install.sh` and `scripts/build.sh` work on stock macOS (BSD find, bash 3.2). Currently both use `mapfile` (bash 4+) and `find -printf` (GNU-only) — fatal on a fresh Mac. Without the fix, the README's "Linux / macOS (bash)" quick-start is a lie.
|
|
||||||
|
|
||||||
## Key files
|
|
||||||
- `scripts/install.sh:11` — `mapfile -t names < <(find ... -printf ...)`
|
|
||||||
- `scripts/build.sh:18` — same pattern
|
|
||||||
- `README.md:30-38` — claims macOS bash quick-start works
|
|
||||||
- `.wiki/concepts/build-notes.md` — companion concept page; add a sibling for the install-script portability gotcha
|
|
||||||
|
|
||||||
## Decisions log
|
|
||||||
- 2026-04-28: Replace `mapfile` + `find -printf` with shell glob (`for d in "$SRC"/*/`). Reason: works in bash 3.2 (stock macOS) and avoids a `find` flavor dependency. Alternative — require `bash 4+` via `#!/usr/bin/env bash` + version check — rejected: pushes the burden onto Mac users, who would need `brew install bash` for a 30-line script.
|
|
||||||
- 2026-04-28: Don't drop the `set -euo pipefail` line — POSIX-ish bash supports it from 3.x.
|
|
||||||
- 2026-04-28: Final — patched both scripts; verified on git-bash (`bash -n` clean, install dry-run installs all 16 skills sorted alphabetically into temp dir, `build.sh active-platform` produces a valid `.skill` archive); wrote `.wiki/concepts/install-portability.md`; index + log updated; dist/ unchanged (smoke-rebuild was byte-identical so no dist churn).
|
|
||||||
|
|
||||||
## Open questions
|
|
||||||
- [ ] None — done.
|
|
||||||
|
|
||||||
## Completed steps
|
|
||||||
- [x] Identify bugs
|
|
||||||
- [x] Pick fix approach (shell glob, no new deps)
|
|
||||||
- [x] Patch `scripts/install.sh`
|
|
||||||
- [x] Patch `scripts/build.sh`
|
|
||||||
- [x] Verify on git-bash (`bash -n` + install dry-run + build smoke-test)
|
|
||||||
- [x] Wiki concept page (`install-portability.md`) + index + log
|
|
||||||
- [x] Commit
|
|
||||||
|
|
||||||
## Notes
|
|
||||||
- `basename` is in POSIX, fine on Mac.
|
|
||||||
- Empty `skills/` would have `"$SRC"/*/` literal under bash 3.2 without `nullglob`. Guard with `[ -d "$d" ] || continue` — works without `shopt`.
|
|
||||||
@@ -1,761 +0,0 @@
|
|||||||
# project-discipline — implementation plan
|
|
||||||
|
|
||||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
||||||
|
|
||||||
**Goal:** Ship a new policy skill `project-discipline` (four cross-project rules: conventions-over-skill-defaults, master-only, semver-bumping, ask-before-push) and wire it into the canonical `project-bootstrap` template, with the `claude-skills` repo dogfooding the trigger.
|
|
||||||
|
|
||||||
**Architecture:** Single-file policy skill (`skills/project-discipline/SKILL.md`) following the `pulling-before-work` shape — frontmatter trigger description + body with four numbered rule sections. `project-bootstrap` v1.4.0 → v1.5.0 adds the canonical trigger line `follow project discipline` to `assets/CLAUDE.md.template` after `pull remote before work`; the existing v1.3.0 idempotent merge propagates it into existing projects on upgrade. The `claude-skills` repo's own `CLAUDE.md` gets the line as dogfood. The bootstrap manifest table gains a row for the new skill. The existing `.wiki/concepts/skill-versioning.md` is extended with a note that Rule 3 expands the versioning requirement from the infra subset to all skills.
|
|
||||||
|
|
||||||
**Tech Stack:** Markdown skills (no build for the skill body itself). Build pipeline: `scripts/build.ps1` produces `dist/<name>.skill` archives. Install: `scripts/install.sh` (portable across git-bash on Windows + native Linux/macOS). Spec lives at `.wiki/concepts/project-discipline-design.md`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## File Structure
|
|
||||||
|
|
||||||
**New:**
|
|
||||||
- `skills/project-discipline/SKILL.md` — frontmatter + body, ~250–300 lines
|
|
||||||
- `skills/project-discipline/README.md` — short user-facing intro mirroring `skills/pulling-before-work/README.md` shape
|
|
||||||
|
|
||||||
**Modified:**
|
|
||||||
- `skills/project-bootstrap/SKILL.md` — `version: 1.4.0` → `1.5.0`; Step 5 inline template gains the new line; new commentary paragraph after the existing `pull remote before work` paragraph; Step 5.5 manifest table gains a row for `project-discipline`
|
|
||||||
- `skills/project-bootstrap/assets/CLAUDE.md.template` — `+ follow project discipline` after `pull remote before work` and before `we're on Windows`
|
|
||||||
- `CLAUDE.md` (repo root) — `+ follow project discipline` in the same position (dogfood)
|
|
||||||
- `.wiki/concepts/skill-versioning.md` — append a section noting Rule 3 of `project-discipline` extends `version:` requirement to ALL skills (not just infra subset)
|
|
||||||
- `.wiki/log.md` — append decision entry
|
|
||||||
- `.wiki/index.md` — concept page link (added when spec was committed; verify still listed; add `project-discipline-design.md` if not)
|
|
||||||
- `.tasks/STATUS.md` — add `[project-discipline-skill]` 🔴 Active block, then update to 🟢 Done at the end
|
|
||||||
|
|
||||||
**Built:**
|
|
||||||
- `dist/project-discipline.skill` — new
|
|
||||||
- `dist/project-bootstrap.skill` — rebuilt
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Task 1: New skill — frontmatter only
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Create: `skills/project-discipline/SKILL.md`
|
|
||||||
|
|
||||||
- [ ] **Step 1: Write the frontmatter**
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
---
|
|
||||||
name: project-discipline
|
|
||||||
version: 0.1.0
|
|
||||||
description: >
|
|
||||||
Codifies four 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. Activated by "follow project discipline" trigger in
|
|
||||||
CLAUDE.md (added by project-bootstrap v1.5.0+).
|
|
||||||
---
|
|
||||||
|
|
||||||
# project-discipline
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 2: Verify description length is under 900 chars**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
$c = Get-Content skills/project-discipline/SKILL.md -Raw
|
|
||||||
$start = $c.IndexOf('description: >') + 'description: >'.Length
|
|
||||||
$end = $c.IndexOf('---', $start)
|
|
||||||
$desc = $c.Substring($start, $end - $start).Trim()
|
|
||||||
"description chars: $($desc.Length)"
|
|
||||||
```
|
|
||||||
Expected: a number ≤ 900. (Per `feedback_skill_description_length_limit` memory: harness silently drops descriptions >~1024 and falls back to the H1.)
|
|
||||||
|
|
||||||
- [ ] **Step 3: Commit**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
git add skills/project-discipline/SKILL.md
|
|
||||||
git commit -m "feat(project-discipline): scaffold skill frontmatter [v0.1.0]"
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Task 2: New skill — body
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Modify: `skills/project-discipline/SKILL.md` (append body)
|
|
||||||
|
|
||||||
- [ ] **Step 1: Append the skill body after the H1**
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
> 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.
|
|
||||||
|
|
||||||
## 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`).
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 2: Sanity-check the file rendered**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
Get-Content skills/project-discipline/SKILL.md | Measure-Object -Line
|
|
||||||
Select-String -Path skills/project-discipline/SKILL.md -Pattern '^## Rule [1-4]'
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected:
|
|
||||||
- Line count ~250–320
|
|
||||||
- Four `## Rule N` matches in order
|
|
||||||
|
|
||||||
- [ ] **Step 3: Commit**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
git add skills/project-discipline/SKILL.md
|
|
||||||
git commit -m "feat(project-discipline): skill body — four rules + activation + out-of-scope [v0.1.0]"
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Task 3: New skill — README.md
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Create: `skills/project-discipline/README.md`
|
|
||||||
|
|
||||||
- [ ] **Step 1: Write README**
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
# 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 `CLAUDE.md` contains the line `follow project discipline` (added by `project-bootstrap` v1.5.0+).
|
|
||||||
- **In-chat** — when the user says "use project discipline", "соблюди дисциплину", "проектные правила", or close variants.
|
|
||||||
|
|
||||||
## The four rules
|
|
||||||
|
|
||||||
1. **Project conventions over skill defaults.** `CLAUDE.md` / `.wiki/CLAUDE.md` / `.tasks/` override any other skill's defaults. Specs go to `.wiki/concepts/`, not `docs/superpowers/specs/`. Tasks to `.tasks/`, not `docs/superpowers/plans/`.
|
|
||||||
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. **Commit yes, push no.** Every session starts asking before push. User can grant auto-push within session ("разреши автопуш"); session end resets to ask-mode. 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
|
|
||||||
`CLAUDE.md` (or use `project-bootstrap` v1.5.0+ which adds it automatically).
|
|
||||||
|
|
||||||
## Related
|
|
||||||
|
|
||||||
- `project-bootstrap` (v1.5.0+) — adds the trigger line to new and existing projects' `CLAUDE.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 `claude-skills`) — full design rationale.
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 2: Commit**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
git add skills/project-discipline/README.md
|
|
||||||
git commit -m "docs(project-discipline): README"
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Task 4: Bootstrap template — add trigger line
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Modify: `skills/project-bootstrap/assets/CLAUDE.md.template`
|
|
||||||
|
|
||||||
- [ ] **Step 1: Insert the new line after `pull remote before work`**
|
|
||||||
|
|
||||||
Use Edit:
|
|
||||||
- `old_string`:
|
|
||||||
```
|
|
||||||
pull remote before work
|
|
||||||
we're on Windows
|
|
||||||
```
|
|
||||||
- `new_string`:
|
|
||||||
```
|
|
||||||
pull remote before work
|
|
||||||
follow project discipline
|
|
||||||
we're on Windows
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 2: Verify**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
Get-Content skills/project-bootstrap/assets/CLAUDE.md.template
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: eight trigger lines in this order:
|
|
||||||
```
|
|
||||||
talk like a caveman
|
|
||||||
use superpowers
|
|
||||||
use project wiki
|
|
||||||
use task management system
|
|
||||||
check across all projects
|
|
||||||
pull remote before work
|
|
||||||
follow project discipline
|
|
||||||
we're on Windows
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 3: Commit**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
git add skills/project-bootstrap/assets/CLAUDE.md.template
|
|
||||||
git commit -m "feat(project-bootstrap): template gains 'follow project discipline' trigger"
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Task 5: Bootstrap SKILL.md — version bump + Step 5 update + manifest row
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Modify: `skills/project-bootstrap/SKILL.md`
|
|
||||||
|
|
||||||
- [ ] **Step 1: Bump version in frontmatter**
|
|
||||||
|
|
||||||
Edit:
|
|
||||||
- `old_string`: `version: 1.4.0`
|
|
||||||
- `new_string`: `version: 1.5.0`
|
|
||||||
|
|
||||||
- [ ] **Step 2: Update the Step 5 inline template (mirror of `assets/CLAUDE.md.template`)**
|
|
||||||
|
|
||||||
Find the fenced markdown block in Step 5:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
talk like a caveman
|
|
||||||
use superpowers
|
|
||||||
use project wiki
|
|
||||||
use task management system
|
|
||||||
check across all projects
|
|
||||||
pull remote before work
|
|
||||||
we're on Windows
|
|
||||||
```
|
|
||||||
|
|
||||||
Replace with:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
talk like a caveman
|
|
||||||
use superpowers
|
|
||||||
use project wiki
|
|
||||||
use task management system
|
|
||||||
check across all projects
|
|
||||||
pull remote before work
|
|
||||||
follow project discipline
|
|
||||||
we're on Windows
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 3: Add commentary paragraph for the new trigger**
|
|
||||||
|
|
||||||
After the existing paragraph that explains `pull remote before work` (ending with "...silently dead like any other absent skill.") and before the paragraph about `we're on Windows` (starting with "The `we're on Windows` line activates..."), insert:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
The `follow project discipline` line activates the `project-discipline` skill,
|
|
||||||
which codifies four cross-project rules: (1) project 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.
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 4: Add `project-discipline` row to Step 5.5 manifest table**
|
|
||||||
|
|
||||||
Find the table:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
| Skill | Version | Role |
|
|
||||||
|---|---|---|
|
|
||||||
| `project-bootstrap` | <version> | orchestrator |
|
|
||||||
| `setup-wiki` | <version> | wiki canonical layout |
|
|
||||||
| `setup-tasks` | <version> | tasks canonical layout |
|
|
||||||
```
|
|
||||||
|
|
||||||
Replace with:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
| Skill | Version | Role |
|
|
||||||
|---|---|---|
|
|
||||||
| `project-bootstrap` | <version> | orchestrator |
|
|
||||||
| `setup-wiki` | <version> | wiki canonical layout |
|
|
||||||
| `setup-tasks` | <version> | tasks canonical layout |
|
|
||||||
| `project-discipline` | <version> | cross-project policy |
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 5: Verify**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
Select-String -Path skills/project-bootstrap/SKILL.md -Pattern '^version:|follow project discipline|project-discipline' | ForEach-Object { "$($_.LineNumber): $($_.Line)" }
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: at least 5 hits — `version: 1.5.0`, the line in the Step 5 fenced block, the new commentary paragraph, the row in the manifest table.
|
|
||||||
|
|
||||||
- [ ] **Step 6: Commit**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
git add skills/project-bootstrap/SKILL.md
|
|
||||||
git commit -m "feat(project-bootstrap): v1.5.0 — add 'follow project discipline' canonical trigger [v1.5.0]"
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Task 6: Update `.wiki/concepts/skill-versioning.md` — note Rule 3 scope extension
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Modify: `.wiki/concepts/skill-versioning.md`
|
|
||||||
|
|
||||||
- [ ] **Step 1: Read current content**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
Get-Content .wiki/concepts/skill-versioning.md
|
|
||||||
```
|
|
||||||
|
|
||||||
Note the existing section "## What skills are versioned" which scopes versioning to the infra subset.
|
|
||||||
|
|
||||||
- [ ] **Step 2: Update the `## What skills are versioned` section**
|
|
||||||
|
|
||||||
Find:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
## What skills are versioned
|
|
||||||
|
|
||||||
Currently only the **infrastructure** skills (the ones bootstrap touches and that govern project layout). Communication-mode skills (`caveman`, family) and discovery skills (`find-skills`, `active-platform`) aren't versioned — their content is "good copy-paste" and a snapshot mismatch isn't a layout problem.
|
|
||||||
|
|
||||||
If we ever start packaging or marketplace-publishing the rest, we'll version them too.
|
|
||||||
```
|
|
||||||
|
|
||||||
Replace with:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
## What skills are versioned
|
|
||||||
|
|
||||||
**Originally** only the **infrastructure** skills (the ones bootstrap touches and that govern project layout). Communication-mode skills (`caveman`, family) and discovery skills (`find-skills`, `active-platform`) were left unversioned — their content was "good copy-paste" and a snapshot mismatch wasn't a layout problem.
|
|
||||||
|
|
||||||
**As of `project-discipline` v0.1.0** (Rule 3), the requirement extends to **all** skills in this repo, regardless of category. Communication-mode and discovery skills also need `version:` in frontmatter; the migration is a separate one-time task tracked in `.tasks/`. Rationale: discipline-by-default is simpler than maintaining a list of "exempt" skills, and it costs nothing — `version: 0.1.0` is added on the next edit per the Rule 3 first-edit-unversioned clause.
|
|
||||||
|
|
||||||
If we ever start packaging or marketplace-publishing skills outside this repo, the same rule still applies.
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 3: Update the frontmatter `updated:` field**
|
|
||||||
|
|
||||||
Find:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
title: Skill versioning + bootstrap manifest
|
|
||||||
type: concept
|
|
||||||
updated: 2026-04-28
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
Replace with:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
title: Skill versioning + bootstrap manifest
|
|
||||||
type: concept
|
|
||||||
updated: 2026-05-01
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 4: Commit**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
git add .wiki/concepts/skill-versioning.md
|
|
||||||
git commit -m "docs(wiki): skill-versioning — Rule 3 of project-discipline extends scope to all skills"
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Task 7: Dogfood — add trigger to claude-skills root CLAUDE.md
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Modify: `CLAUDE.md` (repo root)
|
|
||||||
|
|
||||||
- [ ] **Step 1: Insert the trigger after `pull remote before work`**
|
|
||||||
|
|
||||||
Use Edit:
|
|
||||||
- `old_string`:
|
|
||||||
```
|
|
||||||
pull remote before work
|
|
||||||
we're on Windows
|
|
||||||
```
|
|
||||||
- `new_string`:
|
|
||||||
```
|
|
||||||
pull remote before work
|
|
||||||
follow project discipline
|
|
||||||
we're on Windows
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 2: Verify**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
Get-Content CLAUDE.md
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected:
|
|
||||||
```
|
|
||||||
# CLAUDE.md
|
|
||||||
# Agent instructions. Each line is a trigger for an installed skill.
|
|
||||||
|
|
||||||
talk like a caveman
|
|
||||||
use superpowers
|
|
||||||
use project wiki
|
|
||||||
use task management system
|
|
||||||
check across all projects
|
|
||||||
pull remote before work
|
|
||||||
follow project discipline
|
|
||||||
we're on Windows
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 3: Commit**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
git add CLAUDE.md
|
|
||||||
git commit -m "chore(claude-skills): dogfood 'follow project discipline' trigger"
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Task 8: Build artifacts
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Build: `dist/project-discipline.skill` (new), `dist/project-bootstrap.skill` (rebuilt)
|
|
||||||
|
|
||||||
- [ ] **Step 1: Run the build script**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
pwsh scripts/build.ps1 -Names project-discipline,project-bootstrap
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected output:
|
|
||||||
```
|
|
||||||
built: dist/project-discipline.skill
|
|
||||||
built: dist/project-bootstrap.skill
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 2: Verify the archives**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
Get-ChildItem dist/project-discipline.skill, dist/project-bootstrap.skill | Format-Table Name, Length, LastWriteTime
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: both files exist, `LastWriteTime` is the current minute, sizes nonzero.
|
|
||||||
|
|
||||||
Spot-check the new archive's structure (no Compress-Archive backslash bug — see `.wiki/concepts/build-notes.md`):
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
$arch = [System.IO.Compression.ZipFile]::OpenRead((Resolve-Path dist/project-discipline.skill))
|
|
||||||
$arch.Entries | Select-Object FullName | Format-Table -AutoSize
|
|
||||||
$arch.Dispose()
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: entries like `project-discipline/SKILL.md`, `project-discipline/README.md` — forward slashes only.
|
|
||||||
|
|
||||||
- [ ] **Step 3: Commit**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
git add dist/project-discipline.skill dist/project-bootstrap.skill
|
|
||||||
git commit -m "build: project-discipline@0.1.0 + project-bootstrap@1.5.0 archives"
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Task 9: Install on this machine
|
|
||||||
|
|
||||||
- [ ] **Step 1: Run installer**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
bash scripts/install.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
(`install.sh` is portable — works in git-bash on Windows.)
|
|
||||||
|
|
||||||
Expected stdout: lines like `installed: project-discipline` and `installed: project-bootstrap` (and the rest of the skills, idempotent).
|
|
||||||
|
|
||||||
- [ ] **Step 2: Verify installed skills**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
Test-Path "$env:USERPROFILE\.claude\skills\project-discipline\SKILL.md"
|
|
||||||
Test-Path "$env:USERPROFILE\.claude\skills\project-bootstrap\SKILL.md"
|
|
||||||
Select-String -Path "$env:USERPROFILE\.claude\skills\project-bootstrap\SKILL.md" -Pattern '^version:'
|
|
||||||
Select-String -Path "$env:USERPROFILE\.claude\skills\project-discipline\SKILL.md" -Pattern '^version:'
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected:
|
|
||||||
- both `Test-Path` return `True`
|
|
||||||
- `version: 1.5.0` for project-bootstrap
|
|
||||||
- `version: 0.1.0` for project-discipline
|
|
||||||
|
|
||||||
(No commit — install affects user-level state, not the repo.)
|
|
||||||
|
|
||||||
- [ ] **Step 3: Verify description length post-install**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
$c = Get-Content "$env:USERPROFILE\.claude\skills\project-discipline\SKILL.md" -Raw
|
|
||||||
$start = $c.IndexOf('description: >') + 'description: >'.Length
|
|
||||||
$end = $c.IndexOf('---', $start)
|
|
||||||
$desc = $c.Substring($start, $end - $start).Trim()
|
|
||||||
"description chars: $($desc.Length)"
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: ≤ 900. (Per `feedback_skill_description_length_limit` memory.)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Task 10: Manual smoke validation
|
|
||||||
|
|
||||||
No automated harness — describe what to verify in a fresh session.
|
|
||||||
|
|
||||||
- [ ] **Scenario 1 (skill listing):**
|
|
||||||
|
|
||||||
In a fresh Claude Code session in `claude-skills`, ask the agent: "what skills are available?" or list via `Skill` tool.
|
|
||||||
|
|
||||||
Expected: `project-discipline` appears in the listing with the description from frontmatter (not the H1 fallback). If the description is the H1 ("project-discipline"), the description was silently dropped — check length.
|
|
||||||
|
|
||||||
- [ ] **Scenario 2 (Rule 1 — convention override):**
|
|
||||||
|
|
||||||
In a fresh session, ask the agent to design a small feature that would normally produce a spec. Expected: agent writes spec to `.wiki/concepts/<topic>-design.md`, NOT `docs/superpowers/specs/`. (`brainstorming` skill default would be `docs/superpowers/specs/`; Rule 1 should override.)
|
|
||||||
|
|
||||||
- [ ] **Scenario 3 (Rule 2 — master-only):**
|
|
||||||
|
|
||||||
In a fresh session, ask the agent to "do a small refactor". Expected: agent makes changes on `master` branch, doesn't `git checkout -b`. If the task is borderline, agent asks "needs a branch?".
|
|
||||||
|
|
||||||
- [ ] **Scenario 4 (Rule 3 — version bump):**
|
|
||||||
|
|
||||||
Ask the agent to make any non-trivial edit to a `skills/<name>/SKILL.md` (e.g., add a sentence to body). Expected: the same commit (or the immediately next commit) bumps `version:` in frontmatter per PATCH/MINOR/MAJOR rules. The commit message includes `[vX.Y.Z]`.
|
|
||||||
|
|
||||||
- [ ] **Scenario 5 (Rule 4 — push permission default):**
|
|
||||||
|
|
||||||
After any commit-producing task, expect the agent NOT to push without asking. Expected: agent says something like "готов push'нуть в origin/master, ок?" and waits.
|
|
||||||
|
|
||||||
- [ ] **Scenario 6 (Rule 4 — grant + revoke):**
|
|
||||||
|
|
||||||
In a session, after the agent commits something, say "разреши автопуш". Then make another change. Expected: agent commits AND pushes without asking. Then say "отзови". Make a third change. Expected: agent commits but asks before pushing again.
|
|
||||||
|
|
||||||
- [ ] **Scenario 7 (Rule 4 — force-push exception):**
|
|
||||||
|
|
||||||
With auto-push granted, ask the agent to do something requiring `git push --force` (e.g., simulate by asking: "push --force, ок?"). Expected: agent still asks for confirmation, citing Rule 4 exceptions.
|
|
||||||
|
|
||||||
- [ ] **Scenario 8 (bootstrap upgrade on this very repo):**
|
|
||||||
|
|
||||||
Re-run `project-bootstrap` on `claude-skills` itself in a fresh session: "upgrade project". Expected: bootstrap detects `CLAUDE.md` exists, runs Step 5 idempotent merge, finds `follow project discipline` already present (we added it manually in Task 7), reports `CLAUDE.md already canon — no changes`.
|
|
||||||
|
|
||||||
If Task 7 was skipped, the merge would prompt to append the line. Either way the merge logic works.
|
|
||||||
|
|
||||||
- [ ] **Scenario 9 (description length regression check):**
|
|
||||||
|
|
||||||
Re-run the description length probe (Task 9 Step 3). If the value is > 900, the skill's listing will silently drop the description and substitute H1 — the skill's discoverability collapses. This caught a regression in `using-projects-meta` once; same check protects here.
|
|
||||||
|
|
||||||
- [ ] **Document results in `.tasks/STATUS.md` `Where I stopped` field**
|
|
||||||
|
|
||||||
After running scenarios, update the task block (Task 12 below) with which scenarios passed.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Task 11: Wiki log + index
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Modify: `.wiki/log.md`
|
|
||||||
- Modify: `.wiki/index.md` (verify)
|
|
||||||
|
|
||||||
- [ ] **Step 1: Append log entry**
|
|
||||||
|
|
||||||
Append to `.wiki/log.md`:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
## [2026-05-01] decision | project-discipline — new policy skill (v0.1.0): four cross-project rules (conventions-over-defaults, master-only, semver-bumping, ask-before-push); bootstrap template gains canonical trigger; project-bootstrap 1.4.0→1.5.0; skill-versioning concept extended to all skills
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 2: Verify `.wiki/index.md` lists the design page**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
Select-String -Path .wiki/index.md -Pattern 'project-discipline-design'
|
|
||||||
```
|
|
||||||
|
|
||||||
If absent, add a line under `## Concepts` (alphabetical position — between `pulling-before-work-design` and `repo-layout`):
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
- [project-discipline-design.md](concepts/project-discipline-design.md) — design for project-discipline (four cross-project rules: conventions-over-defaults, master-only, semver-bumping, ask-before-push)
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 3: Commit**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
git add .wiki/log.md .wiki/index.md
|
|
||||||
git commit -m "docs(wiki): log + index — project-discipline@0.1.0"
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Task 12: Tasks board entry — close
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Modify: `.tasks/STATUS.md`
|
|
||||||
|
|
||||||
- [ ] **Step 1: Insert a Done block at the top (after the header) for this task**
|
|
||||||
|
|
||||||
Edit `.tasks/STATUS.md` to add at the very top (immediately after the `_Updated:_` line and a blank line):
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
## 🟢 [project-discipline-skill] — project-discipline skill + project-bootstrap 1.5.0 canonical trigger
|
|
||||||
**Status:** done
|
|
||||||
**Where I stopped:** `skills/project-discipline/` shipped at v0.1.0 (four rules: convention-override, master-only, semver-bumping, session-scoped push permission); `assets/CLAUDE.md.template` gains `follow project discipline` after `pull remote before work`; `project-bootstrap` 1.4.0→1.5.0 with new commentary paragraph in Step 5 + manifest table row in Step 5.5; `.wiki/concepts/skill-versioning.md` extended (Rule 3 expands version: requirement to ALL skills, not just infra subset); root `CLAUDE.md` dogfood line added; both archives rebuilt in `dist/`; installed via `install.sh`; description length verified ≤900 chars; smoke scenarios documented (1/8 verifiable inline; 2-7/9 require fresh sessions for full coverage); design rationale at `.wiki/concepts/project-discipline-design.md`
|
|
||||||
**Next action:** (none — kept until merged)
|
|
||||||
**Branch:** master
|
|
||||||
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 2: Bump the `_Updated:_` line in STATUS.md**
|
|
||||||
|
|
||||||
Find:
|
|
||||||
```markdown
|
|
||||||
_Updated: 2026-05-01_
|
|
||||||
```
|
|
||||||
(or whatever current date is there)
|
|
||||||
|
|
||||||
Replace with:
|
|
||||||
```markdown
|
|
||||||
_Updated: 2026-05-01_
|
|
||||||
```
|
|
||||||
|
|
||||||
(Same date — keep current.)
|
|
||||||
|
|
||||||
- [ ] **Step 3: Commit**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
git add .tasks/STATUS.md .tasks/project-discipline-skill.md
|
|
||||||
git commit -m "tasks: close [project-discipline-skill]"
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Self-Review
|
|
||||||
|
|
||||||
**Spec coverage:**
|
|
||||||
- ✅ Skill activation rules (CLAUDE.md trigger + in-chat reference) → Task 1, 2
|
|
||||||
- ✅ Rule 1 (conventions over defaults) → Task 2 body section
|
|
||||||
- ✅ Rule 2 (master-only) → Task 2 body section
|
|
||||||
- ✅ Rule 3 (versioning, including unversioned-artifact and dist-rebuild clauses) → Task 2 body + Task 6 cross-link to skill-versioning concept
|
|
||||||
- ✅ Rule 4 (session-scoped push permission, with exceptions) → Task 2 body section
|
|
||||||
- ✅ Out-of-scope list → Task 2
|
|
||||||
- ✅ Template change → Task 4
|
|
||||||
- ✅ Bootstrap version bump + Step 5 commentary + Step 5.5 manifest row → Task 5
|
|
||||||
- ✅ skill-versioning concept extension → Task 6
|
|
||||||
- ✅ Dogfood in repo root → Task 7
|
|
||||||
- ✅ Build + install + description-length probe → Tasks 8, 9
|
|
||||||
- ✅ Validation scenarios (covering all four rules + bootstrap merge + length regression) → Task 10
|
|
||||||
- ✅ Wiki log + index → Task 11
|
|
||||||
- ✅ Tasks board close → Task 12
|
|
||||||
|
|
||||||
**Placeholder scan:** no TBD / TODO / "implement later". All steps have explicit code or commands. Manifest row and STATUS block have explicit text, not placeholders. The `<version>` literal in the manifest table is the existing template syntax (filled in by `project-bootstrap` at runtime), not an unfilled spot in this plan.
|
|
||||||
|
|
||||||
**Type / wording consistency:**
|
|
||||||
- Trigger line is `follow project discipline` everywhere (template, dogfood, commentary, README, design doc, plan).
|
|
||||||
- Skill name `project-discipline` everywhere (folder, frontmatter, archive, install path, log, README cross-link, manifest row).
|
|
||||||
- Version `0.1.0` for new skill, `1.5.0` for bootstrap — consistent across frontmatter, log entry, tasks block, build commit, install verification.
|
|
||||||
- "Master-only" / "master/main" wording consistent between Rule 2 and design doc.
|
|
||||||
- Push grant phrases ("разреши автопуш" / "allow auto-push") consistent between Rule 4 wording and validation scenarios.
|
|
||||||
@@ -1,49 +0,0 @@
|
|||||||
# projects-meta-skills
|
|
||||||
|
|
||||||
## Goal
|
|
||||||
Ship a `setup-projects-meta` + `using-projects-meta` skill pair that wraps the local `projects-meta-mcp` server (cross-project task aggregation + shared Gitea-backed wiki). Mirrors the validated `setup-context7` / `using-context7` split: setup is one-time intrusive (clones repo, builds, writes `~/.config/projects-mcp/auth.toml`, clones shared wiki to `~/projects/projects-wiki/`, registers `mcpServers.projects-meta` in `~/.claude.json`), using is daily policy with auto-trigger on cross-project / shared-wiki questions and delegates to setup if `mcp__projects-meta__*` tools are missing.
|
|
||||||
|
|
||||||
## Key files
|
|
||||||
- `skills/setup-projects-meta/SKILL.md` — 8-phase install (model: `skills/setup-context7/SKILL.md`)
|
|
||||||
- `skills/setup-projects-meta/README.md` — human-facing doc (model: `skills/setup-wiki/README.md`)
|
|
||||||
- `skills/using-projects-meta/SKILL.md` — runtime policy (model: `skills/using-context7/SKILL.md`)
|
|
||||||
- `skills/using-projects-meta/README.md` — human-facing doc (model: `skills/using-wiki/README.md`)
|
|
||||||
- `scripts/build.sh` — packages skills into `dist/<name>.skill`
|
|
||||||
- `scripts/install.sh` — copies `skills/<name>/` → `~/.claude/skills/<name>/`
|
|
||||||
|
|
||||||
## Wiki anchors (already in shared wiki)
|
|
||||||
- `packages/projects-meta-mcp` — full reference: paths, auth.toml, tools list, mutation pattern, sync runner
|
|
||||||
- `concepts/setup-using-skill-pair` — pattern: 8-phase setup-X structure, using-X structure, hard rules
|
|
||||||
|
|
||||||
## Decisions log
|
|
||||||
- 2026-04-29: Use `setup-context7` as the structural template for `setup-projects-meta` — same 8-phase shape, same confirmation gates, same rollback section. Reason: pattern already validated end-to-end on context7 (see `feedback_split_policy_from_setup` memory).
|
|
||||||
- 2026-04-29: Use `setup-wiki/README.md` and `using-wiki/README.md` as the README templates — they're more thorough than the context7 pair (which has no READMEs). Adding READMEs upfront avoids re-opening the [skill-readmes] task later.
|
|
||||||
- 2026-04-29: `auth.toml` is the secret-bearing file; never echo `gitea_token` in chat. Edit/Write tool calls inevitably contain it (transcript) — that's OK; chat output must not.
|
|
||||||
- 2026-04-29: `~/.claude.json` `mcpServers.projects-meta` registration uses absolute path to `dist/server.js` (Win path: `C:/Users/<USER>/.local/projects-meta-mcp/dist/server.js`). Forward slashes work on all three platforms.
|
|
||||||
- 2026-04-29: Smoke test in setup phase 7 = `mcp__projects-meta__meta_status` (read-only, returns sync diagnostics). Caveat: in-session smoke only proves "MCP still alive", not "new registration is what's serving" — same caveat as context7.
|
|
||||||
- 2026-04-29: Mutation tools (`tasks_*`, `knowledge_*`) follow two-step preview→confirm pattern; `using-projects-meta` documents the pattern and forbids inlining `confirm: true` without explicit user "ok".
|
|
||||||
- 2026-04-29: Both skills shipped v1.0.0; `setup-projects-meta` description carries Russian + English triggers ("install/set up/configure projects-meta", "настрой/установи projects-meta", "...не работает / isn't working") same shape as setup-context7; `using-projects-meta` description prioritizes cross-project / shared-wiki triggers and explicitly tells the harness to skip for current-project state.
|
|
||||||
- 2026-04-30: After user prodded "почему ты pull не сделал в самом начале?", explicit `git pull` on `~/projects/projects-wiki` revealed `wiki-path-mismatch-resolution.md` — canon path changed from `~/projects/.wiki` (write/read mismatch bug) to `~/projects/projects-wiki/` (clone root) with content at `~/projects/projects-wiki/.wiki/`. Fixed all six places in the new skills (setup SKILL+README, using SKILL+README, concept page, this task file). Phase 1 of setup-projects-meta now detects legacy clone; Phase 4 re-clones to canon. Lesson saved as feedback memory `pull_shared_wiki_explicitly`.
|
|
||||||
|
|
||||||
## Open questions
|
|
||||||
- [ ] `project-bootstrap` Step for `setup-projects-meta`? — concept page says "may be added later as 'recommend installing projects-meta'". Decision: defer, separate task.
|
|
||||||
- [ ] Should `using-projects-meta` carry its own `Local-first rule` or just point to the wiki anchor? Decision: carry it inline — concept page says "for the **current** project read locally; MCP cache is for **other** projects". Critical enough to repeat.
|
|
||||||
|
|
||||||
## Completed steps
|
|
||||||
- [x] Read `setup-context7` + `using-context7` SKILL.md as templates
|
|
||||||
- [x] Fetch `packages/projects-meta-mcp` + `concepts/setup-using-skill-pair` via `knowledge.get`
|
|
||||||
- [x] Inspect `scripts/build.sh` + `scripts/install.sh` + skill folder layouts (setup-context7 = SKILL.md only; setup-wiki = SKILL.md + README.md)
|
|
||||||
- [x] Promote task to 🔴 in STATUS.md
|
|
||||||
- [x] Draft `skills/setup-projects-meta/SKILL.md` (8-phase, model setup-context7)
|
|
||||||
- [x] Draft `skills/using-projects-meta/SKILL.md` (model using-context7, local-first rule + two-step mutation)
|
|
||||||
- [x] Write README.md for both skills (model: setup-wiki / using-wiki)
|
|
||||||
- [x] `bash scripts/build.sh setup-projects-meta using-projects-meta` → both archives in `dist/`
|
|
||||||
- [x] `bash scripts/install.sh ...` → both installed to `~/.claude/skills/`
|
|
||||||
- [x] Smoke: both skills visible in `Skill` tool listing in this session
|
|
||||||
- [x] Wiki: `concepts/projects-meta-skills.md` added; `index.md` + `log.md` updated
|
|
||||||
- [x] Closed task in STATUS.md (🟢 done); next step is round-trip close via `mcp__projects-meta__tasks_close target_project=claude-skills` to mirror state to Gitea
|
|
||||||
|
|
||||||
## Notes
|
|
||||||
- Wiki anchors live in shared `projects-wiki` Gitea repo (`https://git.kzntsv.site/OpeItcLoc03/projects-wiki`), cloned to `~/projects/projects-wiki/.wiki` on this machine.
|
|
||||||
- Original task created from another workstation (`OpeItcLoc03@DESKTOP-NSEF0UK`) via `mcp__projects-meta__tasks_create` — closing it should use `mcp__projects-meta__tasks_close target_project=claude-skills` to round-trip back to the same Gitea board.
|
|
||||||
- After install, restart Claude Code is required for the new MCP tool registrations to bind to a fresh stdio session — same caveat as setup-context7.
|
|
||||||
@@ -1,648 +0,0 @@
|
|||||||
# pulling-before-work — implementation plan
|
|
||||||
|
|
||||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
||||||
|
|
||||||
**Goal:** Ship a new policy skill `pulling-before-work` (one pull at session start + on-demand re-sync) and wire it into the canonical `project-bootstrap` template, with the `claude-skills` repo dogfooding the trigger.
|
|
||||||
|
|
||||||
**Architecture:** Single-file policy skill (`skills/pulling-before-work/SKILL.md`) following the `active-platform` / `using-tasks` shape — frontmatter trigger description + body with deterministic shell algorithm. `project-bootstrap` v1.4.0 adds the canonical trigger line `pull remote before work` to `assets/CLAUDE.md.template`; the existing v1.3.0 idempotent merge propagates it into existing projects on upgrade. The `claude-skills` repo's own `CLAUDE.md` gets the line as dogfood.
|
|
||||||
|
|
||||||
**Tech Stack:** Markdown skills (no build for the skill body itself). Build pipeline: `scripts/build.ps1` produces `dist/<name>.skill` archives. Install: `scripts/install.sh` (or `.ps1`). Spec lives at `.wiki/concepts/pulling-before-work-design.md`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## File Structure
|
|
||||||
|
|
||||||
**New:**
|
|
||||||
- `skills/pulling-before-work/SKILL.md` — frontmatter + body, ~80–120 lines
|
|
||||||
- `skills/pulling-before-work/README.md` — short user-facing intro mirroring `skills/using-tasks/README.md` shape
|
|
||||||
|
|
||||||
**Modified:**
|
|
||||||
- `skills/project-bootstrap/SKILL.md` — `version: 1.3.0` → `1.4.0`; Step 5 inline template gains the new line; new commentary paragraph after the inline template explaining the trigger (mirrors the existing paragraphs about `check across all projects` and `we're on Windows`)
|
|
||||||
- `skills/project-bootstrap/assets/CLAUDE.md.template` — `+ pull remote before work` before `we're on Windows`
|
|
||||||
- `CLAUDE.md` (repo root) — `+ pull remote before work` before `we're on Windows` (dogfood)
|
|
||||||
- `.wiki/log.md` — append decision entry
|
|
||||||
- `.wiki/index.md` — concept page link (added in spec commit; verify still listed)
|
|
||||||
- `.tasks/STATUS.md` — add `[pulling-before-work-skill]` block
|
|
||||||
|
|
||||||
**Built:**
|
|
||||||
- `dist/pulling-before-work.skill` — new
|
|
||||||
- `dist/project-bootstrap.skill` — rebuilt
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Task 1: New skill — frontmatter only
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Create: `skills/pulling-before-work/SKILL.md`
|
|
||||||
|
|
||||||
- [ ] **Step 1: Write the frontmatter**
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
---
|
|
||||||
name: pulling-before-work
|
|
||||||
version: 1.0.0
|
|
||||||
description: >
|
|
||||||
Pulls the current branch from origin once at session start and on explicit
|
|
||||||
re-sync requests. Use when CLAUDE.md contains the trigger line "pull remote
|
|
||||||
before work", or when the user says "sync", "resync", "pull", "обнови репо",
|
|
||||||
"git pull please", or close variants asking to refresh from the remote.
|
|
||||||
Runs `git pull --ff-only` — never auto-merges or rebases. Stays silent in
|
|
||||||
non-git folders. Prints one informational line and exits when there is no
|
|
||||||
origin remote, no upstream tracking, the working tree is dirty, or HEAD is
|
|
||||||
detached. Does not stash, commit, or push. Activated by `project-bootstrap`
|
|
||||||
v1.4.0+ via the canonical CLAUDE.md template.
|
|
||||||
---
|
|
||||||
|
|
||||||
# pulling-before-work
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 2: Verify description length is under 900 chars**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
```powershell
|
|
||||||
$c = Get-Content skills/pulling-before-work/SKILL.md -Raw
|
|
||||||
$start = $c.IndexOf('description: >') + 'description: >'.Length
|
|
||||||
$end = $c.IndexOf('---', $start)
|
|
||||||
$desc = $c.Substring($start, $end - $start).Trim()
|
|
||||||
"description chars: $($desc.Length)"
|
|
||||||
```
|
|
||||||
Expected: a number ≤ 900. (Per `feedback_skill_description_length_limit` memory: harness silently drops descriptions >~1024 and falls back to the H1.)
|
|
||||||
|
|
||||||
- [ ] **Step 3: Commit**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
git add skills/pulling-before-work/SKILL.md
|
|
||||||
git commit -m "feat(pulling-before-work): scaffold skill frontmatter"
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Task 2: New skill — body
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Modify: `skills/pulling-before-work/SKILL.md` (append body)
|
|
||||||
|
|
||||||
- [ ] **Step 1: Append the skill body after the H1**
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
> Pull from `origin` once when work starts. Don't auto-merge. Don't trample dirty work-trees. Don't ask twice in the same session unless asked.
|
|
||||||
|
|
||||||
## When this runs
|
|
||||||
|
|
||||||
**At session start** — once, when the skill is activated by the `pull remote before work` line in `CLAUDE.md`. The cycle below runs immediately.
|
|
||||||
|
|
||||||
**On explicit re-sync** — when the user says any of: `sync`, `resync`, `pull`, `обнови репо`, `pull please`, `git pull`, `подтяни`, `pull from origin`. Re-runs the full cycle. There is no per-session counter; the user is always allowed to ask.
|
|
||||||
|
|
||||||
**Never** before each commit, before each tool call, on every message, or in any other implicit cadence. Mode-3 ("start + on-demand") was the explicit design choice — see `.wiki/concepts/pulling-before-work-design.md`.
|
|
||||||
|
|
||||||
## The pull cycle
|
|
||||||
|
|
||||||
Run these checks in order. Print at most one line of chat output per run.
|
|
||||||
|
|
||||||
### 1. Inside a git work-tree?
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git rev-parse --is-inside-work-tree 2>/dev/null
|
|
||||||
```
|
|
||||||
|
|
||||||
If the command fails or prints anything other than `true` → **exit silently, no chat output.** This is the not-a-git-repo case; the skill must not be noisy in random folders.
|
|
||||||
|
|
||||||
### 2. Has an `origin` remote?
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git remote get-url origin 2>/dev/null
|
|
||||||
```
|
|
||||||
|
|
||||||
If the command fails (no such remote) → print one line and exit:
|
|
||||||
|
|
||||||
```
|
|
||||||
no origin remote — skip pull
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. Is the working tree clean?
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git status --porcelain
|
|
||||||
```
|
|
||||||
|
|
||||||
If the output is non-empty → print one line and exit:
|
|
||||||
|
|
||||||
```
|
|
||||||
working tree dirty — skipping pull. commit/stash, потом скажи "sync"
|
|
||||||
```
|
|
||||||
|
|
||||||
Never stash automatically. Stash-pop conflicts are exactly the friction this skill exists to remove.
|
|
||||||
|
|
||||||
### 4. Is HEAD attached?
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git symbolic-ref -q HEAD
|
|
||||||
```
|
|
||||||
|
|
||||||
If the command fails (empty output, exit 1) → detached HEAD. Print:
|
|
||||||
|
|
||||||
```
|
|
||||||
detached HEAD — skip pull
|
|
||||||
```
|
|
||||||
|
|
||||||
### 5. Does the current branch have an upstream?
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git rev-parse --abbrev-ref --symbolic-full-name '@{u}' 2>/dev/null
|
|
||||||
```
|
|
||||||
|
|
||||||
Capture the upstream name (e.g. `origin/master`). If the command fails → no upstream tracking. Print:
|
|
||||||
|
|
||||||
```
|
|
||||||
no upstream tracking for <branch> — skip pull
|
|
||||||
```
|
|
||||||
|
|
||||||
(Where `<branch>` is `git rev-parse --abbrev-ref HEAD`.)
|
|
||||||
|
|
||||||
### 6. Pull, fast-forward only
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git pull --ff-only
|
|
||||||
```
|
|
||||||
|
|
||||||
(No args — uses the configured upstream captured above.)
|
|
||||||
|
|
||||||
Classify by exit code and stdout:
|
|
||||||
|
|
||||||
| Result | Print |
|
|
||||||
|---|---|
|
|
||||||
| Already up to date | `✅ already up to date with <upstream>` |
|
|
||||||
| Fast-forward, N commits | `✅ pulled N commits from <upstream>` |
|
|
||||||
| Non-fast-forward / diverged (exit non-zero with "diverged" or "non-fast-forward" in output) | `⚠️ diverged from <upstream> — resolve manually (git pull --rebase or merge); skill never auto-merges/rebases` |
|
|
||||||
|
|
||||||
### Out of scope
|
|
||||||
|
|
||||||
The skill never:
|
|
||||||
|
|
||||||
- commits, stashes, or pushes
|
|
||||||
- recurses into submodules
|
|
||||||
- pulls from non-`origin` remotes
|
|
||||||
- pulls on detached HEAD
|
|
||||||
- runs auto-merge or auto-rebase
|
|
||||||
- runs more than once per session unless the user asks
|
|
||||||
|
|
||||||
## Recovery hints
|
|
||||||
|
|
||||||
If the skill skipped because of a dirty tree:
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
# Windows / PowerShell
|
|
||||||
git status # see what's dirty
|
|
||||||
git add . ; git commit -m "wip"
|
|
||||||
# then ask the agent: "sync"
|
|
||||||
```
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Linux / macOS
|
|
||||||
git status
|
|
||||||
git add . && git commit -m "wip"
|
|
||||||
# then say "sync"
|
|
||||||
```
|
|
||||||
|
|
||||||
If the skill reported `diverged`:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Option A: rebase your local commits on top of origin
|
|
||||||
git pull --rebase
|
|
||||||
|
|
||||||
# Option B: explicit merge (creates a merge commit)
|
|
||||||
git pull --no-ff
|
|
||||||
```
|
|
||||||
|
|
||||||
The skill stays out of these decisions on purpose — both options have valid use cases and the user owns the choice.
|
|
||||||
|
|
||||||
## Why this exists
|
|
||||||
|
|
||||||
Stale local branches are a silent footgun: edits land on top of yesterday's `origin`, the divergence shows up at push time, and by then there's a chunk of work to rebase or merge on the wrong base. One pull at start covers the common case; an explicit re-sync trigger handles long sessions where someone pushed mid-flight.
|
|
||||||
|
|
||||||
Full design rationale (mode choice, dirty-tree skip vs stash, `--ff-only` vs auto-merge, the upstream-check) lives in `.wiki/concepts/pulling-before-work-design.md`.
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 2: Sanity-check the file rendered**
|
|
||||||
|
|
||||||
Read the file back and confirm:
|
|
||||||
- Frontmatter still parses (no `---` accidentally inside the body)
|
|
||||||
- All six numbered steps are present
|
|
||||||
- Recovery hints block has both PowerShell and bash variants
|
|
||||||
|
|
||||||
- [ ] **Step 3: Commit**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
git add skills/pulling-before-work/SKILL.md
|
|
||||||
git commit -m "feat(pulling-before-work): skill body — pull cycle, recovery hints, rationale"
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Task 3: New skill — README.md
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Create: `skills/pulling-before-work/README.md`
|
|
||||||
|
|
||||||
- [ ] **Step 1: Write README**
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
# pulling-before-work
|
|
||||||
|
|
||||||
Policy skill that pulls the current branch from `origin` once at session start
|
|
||||||
and on explicit re-sync requests. Designed to remove the "edited on stale base"
|
|
||||||
footgun without trampling dirty work-trees or auto-merging.
|
|
||||||
|
|
||||||
## When it triggers
|
|
||||||
|
|
||||||
- **Session start** — when `CLAUDE.md` contains the line `pull remote before work` (added by `project-bootstrap` v1.4.0+).
|
|
||||||
- **In-chat** — when the user says `sync`, `resync`, `pull`, `обнови репо`, `git pull please`, or close variants.
|
|
||||||
|
|
||||||
Stays silent in non-git folders. Prints one informational line and exits in:
|
|
||||||
no `origin` remote, no upstream tracking, dirty work-tree, detached HEAD.
|
|
||||||
|
|
||||||
## What it does
|
|
||||||
|
|
||||||
`git pull --ff-only` against the configured upstream — never auto-merges, never
|
|
||||||
auto-rebases, never stashes, never commits, never pushes. On divergence it prints
|
|
||||||
a warning with manual-resolution hints and exits.
|
|
||||||
|
|
||||||
## Prerequisites
|
|
||||||
|
|
||||||
None. The skill is a no-op outside git repos and folders without an `origin`
|
|
||||||
remote, so it's safe to leave activated everywhere.
|
|
||||||
|
|
||||||
## Related
|
|
||||||
|
|
||||||
- `project-bootstrap` (v1.4.0+) — adds the trigger line to new and existing projects' `CLAUDE.md`.
|
|
||||||
- `.wiki/concepts/pulling-before-work-design.md` (in projects bootstrapped from this repo: this design lives in `claude-skills`) — full design rationale.
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 2: Commit**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
git add skills/pulling-before-work/README.md
|
|
||||||
git commit -m "docs(pulling-before-work): README"
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Task 4: Bootstrap template — add trigger line
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Modify: `skills/project-bootstrap/assets/CLAUDE.md.template`
|
|
||||||
|
|
||||||
- [ ] **Step 1: Insert the new line before the platform line**
|
|
||||||
|
|
||||||
Current:
|
|
||||||
```markdown
|
|
||||||
# CLAUDE.md
|
|
||||||
# Agent instructions. Each line is a trigger for an installed skill.
|
|
||||||
|
|
||||||
talk like a caveman
|
|
||||||
use superpowers
|
|
||||||
use project wiki
|
|
||||||
use task management system
|
|
||||||
check across all projects
|
|
||||||
we're on Windows
|
|
||||||
```
|
|
||||||
|
|
||||||
Target:
|
|
||||||
```markdown
|
|
||||||
# CLAUDE.md
|
|
||||||
# Agent instructions. Each line is a trigger for an installed skill.
|
|
||||||
|
|
||||||
talk like a caveman
|
|
||||||
use superpowers
|
|
||||||
use project wiki
|
|
||||||
use task management system
|
|
||||||
check across all projects
|
|
||||||
pull remote before work
|
|
||||||
we're on Windows
|
|
||||||
```
|
|
||||||
|
|
||||||
Use `Edit` with `old_string="check across all projects\nwe're on Windows"` → `new_string="check across all projects\npull remote before work\nwe're on Windows"`.
|
|
||||||
|
|
||||||
- [ ] **Step 2: Verify**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
Get-Content skills/project-bootstrap/assets/CLAUDE.md.template
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: the seven trigger lines above, in that order.
|
|
||||||
|
|
||||||
- [ ] **Step 3: Commit**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
git add skills/project-bootstrap/assets/CLAUDE.md.template
|
|
||||||
git commit -m "feat(project-bootstrap): template gains 'pull remote before work' trigger"
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Task 5: Bootstrap SKILL.md — version bump + Step 5 update
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Modify: `skills/project-bootstrap/SKILL.md`
|
|
||||||
|
|
||||||
- [ ] **Step 1: Bump version in frontmatter**
|
|
||||||
|
|
||||||
Edit:
|
|
||||||
- `old`: `version: 1.3.0`
|
|
||||||
- `new`: `version: 1.4.0`
|
|
||||||
|
|
||||||
- [ ] **Step 2: Update the Step 5 inline template (mirror of `assets/CLAUDE.md.template`)**
|
|
||||||
|
|
||||||
In Step 5, find the fenced markdown block:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
talk like a caveman
|
|
||||||
use superpowers
|
|
||||||
use project wiki
|
|
||||||
use task management system
|
|
||||||
check across all projects
|
|
||||||
we're on Windows
|
|
||||||
```
|
|
||||||
|
|
||||||
Replace with:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
talk like a caveman
|
|
||||||
use superpowers
|
|
||||||
use project wiki
|
|
||||||
use task management system
|
|
||||||
check across all projects
|
|
||||||
pull remote before work
|
|
||||||
we're on Windows
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 3: Add commentary paragraph for the new trigger**
|
|
||||||
|
|
||||||
After the existing paragraph that explains `check across all projects` and before the paragraph about `we're on Windows`, insert:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
The `pull remote before work` line activates the `pulling-before-work` skill,
|
|
||||||
which runs one `git pull --ff-only` at session start (and on explicit re-sync
|
|
||||||
requests like "sync"). It's a no-op outside git repos and skips with a one-line
|
|
||||||
warning if the working tree is dirty, HEAD is detached, or the branch has no
|
|
||||||
upstream — never auto-merges, stashes, or pushes. Install the skill on the host
|
|
||||||
if `pulling-before-work` is not in `~/.claude/skills/`; otherwise the trigger is
|
|
||||||
silently dead like any other absent skill.
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 4: Verify**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
Select-String -Path skills/project-bootstrap/SKILL.md -Pattern '^version:|pull remote before work|pulling-before-work' | ForEach-Object { "$($_.LineNumber): $($_.Line)" }
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: at least 4 hits — `version: 1.4.0`, the line in the Step 5 fenced block, the new commentary paragraph mentioning the trigger, and a reference to `pulling-before-work`.
|
|
||||||
|
|
||||||
- [ ] **Step 5: Commit**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
git add skills/project-bootstrap/SKILL.md
|
|
||||||
git commit -m "feat(project-bootstrap): v1.4.0 — add 'pull remote before work' canonical trigger"
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Task 6: Dogfood — add trigger to claude-skills root CLAUDE.md
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Modify: `CLAUDE.md` (repo root)
|
|
||||||
|
|
||||||
- [ ] **Step 1: Insert the trigger before the platform line**
|
|
||||||
|
|
||||||
Use Edit:
|
|
||||||
- `old`: `check across all projects\nwe're on Windows`
|
|
||||||
- `new`: `check across all projects\npull remote before work\nwe're on Windows`
|
|
||||||
|
|
||||||
- [ ] **Step 2: Verify**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
Get-Content CLAUDE.md
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected:
|
|
||||||
```
|
|
||||||
# CLAUDE.md
|
|
||||||
# Agent instructions. Each line is a trigger for an installed skill.
|
|
||||||
|
|
||||||
talk like a caveman
|
|
||||||
use superpowers
|
|
||||||
use project wiki
|
|
||||||
use task management system
|
|
||||||
check across all projects
|
|
||||||
pull remote before work
|
|
||||||
we're on Windows
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 3: Commit**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
git add CLAUDE.md
|
|
||||||
git commit -m "chore(claude-skills): dogfood 'pull remote before work' trigger"
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Task 7: Build artifacts
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Build: `dist/pulling-before-work.skill` (new), `dist/project-bootstrap.skill` (rebuilt)
|
|
||||||
|
|
||||||
- [ ] **Step 1: Run the build script**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
pwsh scripts/build.ps1 -Names pulling-before-work,project-bootstrap
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected output:
|
|
||||||
```
|
|
||||||
built: dist/pulling-before-work.skill
|
|
||||||
built: dist/project-bootstrap.skill
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 2: Verify the archives**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
Get-ChildItem dist/pulling-before-work.skill, dist/project-bootstrap.skill | Format-Table Name, Length, LastWriteTime
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: both files exist, `LastWriteTime` is the current minute, sizes nonzero.
|
|
||||||
|
|
||||||
Spot-check the new archive's structure (no Compress-Archive backslash bug):
|
|
||||||
```powershell
|
|
||||||
$arch = [System.IO.Compression.ZipFile]::OpenRead((Resolve-Path dist/pulling-before-work.skill))
|
|
||||||
$arch.Entries | Select-Object FullName | Format-Table -AutoSize
|
|
||||||
$arch.Dispose()
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected: entries like `pulling-before-work/SKILL.md`, `pulling-before-work/README.md` — forward slashes, no backslashes.
|
|
||||||
|
|
||||||
- [ ] **Step 3: Commit**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
git add dist/pulling-before-work.skill dist/project-bootstrap.skill
|
|
||||||
git commit -m "build: pulling-before-work@1.0.0 + project-bootstrap@1.4.0 archives"
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Task 8: Install on this machine
|
|
||||||
|
|
||||||
- [ ] **Step 1: Run installer**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
bash scripts/install.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
(`install.sh` is portable — works in git-bash on Windows. No `.ps1` exists yet; that's a separate ⚪ Ready task `[install-ps1]`.)
|
|
||||||
|
|
||||||
Expected stdout: lines like `installed: pulling-before-work` and `installed: project-bootstrap` (and the rest of the skills, idempotent).
|
|
||||||
|
|
||||||
- [ ] **Step 2: Verify installed skills**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
Test-Path "$env:USERPROFILE\.claude\skills\pulling-before-work\SKILL.md"
|
|
||||||
Test-Path "$env:USERPROFILE\.claude\skills\project-bootstrap\SKILL.md"
|
|
||||||
Select-String -Path "$env:USERPROFILE\.claude\skills\project-bootstrap\SKILL.md" -Pattern '^version:'
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected:
|
|
||||||
- both `Test-Path` return `True`
|
|
||||||
- `version: 1.4.0` for project-bootstrap
|
|
||||||
|
|
||||||
(No commit — install affects user-level state, not the repo.)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Task 9: Manual smoke validation
|
|
||||||
|
|
||||||
Validation per spec scenarios. No automated harness — run each in a scratch dir or describe what to verify.
|
|
||||||
|
|
||||||
- [ ] **Scenario 1 (clean repo with remote, up to date):**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
$tmp = Join-Path $env:TEMP "pull-smoke-1"
|
|
||||||
git clone https://github.com/anthropics/claude-code $tmp
|
|
||||||
cd $tmp
|
|
||||||
# In a *new* Claude Code session opened in $tmp with `pull remote before work` in CLAUDE.md,
|
|
||||||
# expect the agent to print: "✅ already up to date with origin/main"
|
|
||||||
```
|
|
||||||
|
|
||||||
This requires running a fresh agent session. Document the expected line in chat as proof.
|
|
||||||
|
|
||||||
- [ ] **Scenario 2 (no remote):**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
$tmp = Join-Path $env:TEMP "pull-smoke-2"
|
|
||||||
New-Item -Type Directory $tmp | Out-Null
|
|
||||||
cd $tmp
|
|
||||||
git init
|
|
||||||
"pull remote before work" | Out-File CLAUDE.md
|
|
||||||
# Open agent session here. Expect: "no origin remote — skip pull"
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Scenario 4 (dirty tree):**
|
|
||||||
|
|
||||||
In a clean repo with origin, `Set-Content -Path test.txt -Value "wip"`. Open agent session. Expect: `working tree dirty — skipping pull. commit/stash, потом скажи "sync"`.
|
|
||||||
|
|
||||||
- [ ] **Scenario 8 (bootstrap upgrade on this very repo):**
|
|
||||||
|
|
||||||
Re-run `project-bootstrap` on `claude-skills` itself:
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
# In a fresh Claude Code session in claude-skills root, say: "upgrade project"
|
|
||||||
# Bootstrap detects CLAUDE.md exists, runs Step 5 idempotent merge.
|
|
||||||
# Expected: it reports CLAUDE.md is already canon (we added the line manually
|
|
||||||
# in Task 6, so the merge sees nothing missing). No prompt to append.
|
|
||||||
```
|
|
||||||
|
|
||||||
If Task 6 was skipped accidentally, this scenario would prompt to append `pull remote before work`. Either way demonstrates the merge logic works.
|
|
||||||
|
|
||||||
- [ ] **Document results in `.tasks/STATUS.md` `Where I stopped` field**
|
|
||||||
|
|
||||||
After running scenarios, update the task block (Task 11 below) with which scenarios passed.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Task 10: Wiki log + index
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Modify: `.wiki/log.md`
|
|
||||||
- Modify: `.wiki/index.md` (verify)
|
|
||||||
|
|
||||||
- [ ] **Step 1: Append log entry**
|
|
||||||
|
|
||||||
Append to `.wiki/log.md`:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
## [2026-05-01] decision | pulling-before-work — new policy skill (v1.0.0): one `git pull --ff-only` at session start + on-demand re-sync; bootstrap template gains canonical trigger; project-bootstrap 1.3.0→1.4.0
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 2: Verify `.wiki/index.md` lists the design page**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
Select-String -Path .wiki/index.md -Pattern 'pulling-before-work-design'
|
|
||||||
```
|
|
||||||
|
|
||||||
If absent, add a line under `## Concepts`:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
- [pulling-before-work-design.md](concepts/pulling-before-work-design.md) — design for the pulling-before-work skill (mode-3 + skip-on-dirty)
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 3: Commit**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
git add .wiki/log.md .wiki/index.md
|
|
||||||
git commit -m "docs(wiki): log + index — pulling-before-work@1.0.0"
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Task 11: Tasks board entry
|
|
||||||
|
|
||||||
**Files:**
|
|
||||||
- Modify: `.tasks/STATUS.md`
|
|
||||||
|
|
||||||
- [ ] **Step 1: Insert a Done block at the top (after the header) for this task**
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
## 🟢 [pulling-before-work-skill] — pulling-before-work skill + project-bootstrap 1.4.0 canonical trigger
|
|
||||||
**Status:** done
|
|
||||||
**Where I stopped:** `skills/pulling-before-work/` shipped at v1.0.0 (mode-3 activation: session start + on-demand re-sync; `git pull --ff-only`; skips on no-remote / no-upstream / dirty / detached); `assets/CLAUDE.md.template` gains `pull remote before work`; `project-bootstrap` 1.3.0→1.4.0 with new commentary paragraph in Step 5; root `CLAUDE.md` dogfood line added; both archives rebuilt in `dist/`; installed via `install.sh`; smoke scenarios 1/2/4/8 verified manually; design rationale at `.wiki/concepts/pulling-before-work-design.md`
|
|
||||||
**Next action:** (none — kept until merged)
|
|
||||||
**Branch:** master
|
|
||||||
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] **Step 2: Commit**
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
git add .tasks/STATUS.md .tasks/pulling-before-work-skill.md
|
|
||||||
git commit -m "tasks: close [pulling-before-work-skill]"
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Self-Review
|
|
||||||
|
|
||||||
**Spec coverage:**
|
|
||||||
- ✅ Skill description / activation rules → Task 1, 2
|
|
||||||
- ✅ Pull cycle (6 steps incl. upstream check) → Task 2
|
|
||||||
- ✅ Out-of-scope list → Task 2
|
|
||||||
- ✅ Mode-3 + skip-on-dirty + `--ff-only` rationale → Task 2 (body) + design doc cross-ref
|
|
||||||
- ✅ Template change → Task 4
|
|
||||||
- ✅ Bootstrap version bump + Step 5 commentary → Task 5
|
|
||||||
- ✅ Dogfood in repo root → Task 6
|
|
||||||
- ✅ Build + install → Tasks 7, 8
|
|
||||||
- ✅ Validation scenarios → Task 9
|
|
||||||
- ✅ Wiki + tasks bookkeeping → Tasks 10, 11
|
|
||||||
|
|
||||||
**Placeholder scan:** no TBD / TODO / "implement later". All steps have explicit code or commands.
|
|
||||||
|
|
||||||
**Type / wording consistency:** trigger line is `pull remote before work` everywhere (template, dogfood, commentary, README, design). Skill name `pulling-before-work` everywhere (folder, frontmatter, archive, install path, log, README cross-link). Version `1.0.0` for new skill, `1.4.0` for bootstrap — consistent across frontmatter, log, tasks block.
|
|
||||||
@@ -1,26 +0,0 @@
|
|||||||
# shared-wiki-skill-catalog
|
|
||||||
|
|
||||||
## Goal
|
|
||||||
Опубликовать в shared `projects-wiki` сводный каталог скиллов из `claude-skills`, чтобы агенты на других машинах / в других репах могли быстро увидеть, какие скиллы существуют, в какой версии, и сгруппированы как. Дополняет уже существующую страницу `concepts/setup-using-skill-pair` (паттерн), но не дублирует её — каталог — это `packages/claude-skills`.
|
|
||||||
|
|
||||||
## Key files
|
|
||||||
- `c:\Users\vitya\projects\claude-skills\skills\*\SKILL.md` — источник имён, версий, описаний
|
|
||||||
- `c:\Users\vitya\projects\projects-wiki\.wiki\packages\claude-skills.md` — итоговая страница (создаётся через `knowledge_ingest`)
|
|
||||||
- `c:\Users\vitya\projects\projects-wiki\.wiki\concepts\setup-using-skill-pair.md` — связанная страница (паттерн)
|
|
||||||
|
|
||||||
## Decisions log
|
|
||||||
- 2026-05-01: Один comprehensive page `packages/claude-skills` вместо россыпи `entities/<skill>.md`. Причина: 20 скиллов с короткими description — entity-страницы стали бы пустыми; одна сгруппированная таблица читается быстрее и легче поддерживать
|
|
||||||
- 2026-05-01: Группировка по назначению (communication / bootstrap / wiki+tasks / MCP / discovery / platform), не по алфавиту
|
|
||||||
- 2026-05-01: Версия указана только если присутствует в frontmatter (не выдумываем 0.1.0 для unversioned, чтобы не давать ложного сигнала)
|
|
||||||
|
|
||||||
## Open questions
|
|
||||||
- [ ] Стоит ли потом отдельные `entities/<skill>.md` для скиллов с глубоким design rationale (project-bootstrap, project-discipline)? Решим, если кто-то реально захочет drill-down
|
|
||||||
|
|
||||||
## Completed steps
|
|
||||||
- [x] Step 0 freshness gate (cache 73 мин stale → search OK; shared wiki pulled clean)
|
|
||||||
- [x] Прочитан index shared wiki (нет коллизий: ни `packages/claude-skills`, ни catalog page нет)
|
|
||||||
- [x] Прочитаны frontmatter всех 20 SKILL.md
|
|
||||||
- [x] Создана сама страница через `knowledge_ingest` (preview → confirm)
|
|
||||||
|
|
||||||
## Notes
|
|
||||||
Cross-link: `concepts/setup-using-skill-pair` (паттерн), `packages/projects-meta-mcp` (один из MCP серверов, для которого скиллы из этого репа являются клиентами).
|
|
||||||
@@ -1,34 +0,0 @@
|
|||||||
# using-projects-meta-freshness-gate
|
|
||||||
|
|
||||||
## Goal
|
|
||||||
Add an explicit Step 0 "Freshness gate" to `using-projects-meta` so the agent does not hit a stale MCP cache or a sha-based optimistic-lock conflict in cross-machine workflows. Pre-flight: always `meta_status`; if `cache_age` > 10 min or `errors_count` > 0, run `node ~/.local/projects-meta-mcp/dist/sync.js` for reads; for shared-wiki writes (`knowledge_ingest`, `knowledge_promote`) additionally `git -C ~/projects/projects-wiki pull --ff-only`. 401/403 from sync → token expired → send user to `~/.config/projects-mcp/auth.toml`. Tasks-mutations need only the sync (no local clone of target tasks repo). Bump skill 1.0.0 → 1.1.0 (additive, non-breaking).
|
|
||||||
|
|
||||||
## Key files
|
|
||||||
- `skills/using-projects-meta/SKILL.md` — add **Step 0 — Freshness gate** section before "Read (no confirmation needed)" and before "Mutate (always two-step)"; tweak Workflow ordering
|
|
||||||
- `skills/using-projects-meta/README.md` — mirror the rule in a new "Freshness gate" subsection of "Two operation classes"
|
|
||||||
- `.wiki/concepts/projects-meta-skills.md` — append a "Freshness gate (v1.1.0)" subsection
|
|
||||||
- `.wiki/log.md` — one entry
|
|
||||||
|
|
||||||
## Decisions log
|
|
||||||
- 2026-04-30: Threshold = 10 min cache age. Reason: balance between catching cross-machine pushes and not hitting Gitea on every casual `tasks_aggregate`. User-supplied number, codified.
|
|
||||||
- 2026-04-30: For shared-wiki writes, pull is **unconditional** (not gated by cache age). Reason: sha-based optimistic lock in `knowledge_ingest` will reject the commit otherwise with a 422, and the failure mode is opaque ("why did it fail?"). The pull is cheap (fast-forward is a no-op when already current).
|
|
||||||
- 2026-04-30: For tasks-mutations, sync via `dist/sync.js` is enough. Reason: there's no local clone of the target tasks repo — mutations go straight through Gitea API. The sync only refreshes the local view of all repos' STATUS.md so the agent reasons from current state when writing.
|
|
||||||
- 2026-04-30: 401/403 from sync → send user to rotate `gitea_token` in `~/.config/projects-mcp/auth.toml`. Reason: silently failing or pretending sync succeeded leaves the agent reasoning on stale data. Loud failure is the whole point of the check.
|
|
||||||
- 2026-04-30: Version bump 1.0.0 → 1.1.0 (additive behavior change — adds a pre-flight step, doesn't break existing usage). `using-context7` precedent: `version` in frontmatter, semver discipline.
|
|
||||||
|
|
||||||
## Open questions
|
|
||||||
- [ ] Should Step 0 apply to `meta_status` itself? Decision: no — that would be circular. `meta_status` is the freshness probe, not a read that depends on freshness.
|
|
||||||
|
|
||||||
## Completed steps
|
|
||||||
- [x] Open task in STATUS.md as 🔴 active
|
|
||||||
- [x] Add Step 0 — Freshness gate section to `using-projects-meta/SKILL.md` (between Workflow header and Read sub-section); add Step 0 reference to Read and Mutate sub-flows; extend Common mistakes (3 new rows: stale aggregate, skipped pull, sync 401/403); extend Red flags (2 new bullets)
|
|
||||||
- [x] Mirror rule in `using-projects-meta/README.md` as new "Step 0 — Freshness gate (v1.1.0, mandatory pre-flight)" section
|
|
||||||
- [x] Bump `version: 1.0.0` → `1.1.0` in SKILL.md frontmatter
|
|
||||||
- [x] First rebuild + reinstall — caused regression: full Step 0 inlined into description took it to ~1450 chars, exceeded harness limit, description silently dropped → listing showed `using-projects-meta: Using the projects-meta MCP server` (H1 fallback); fixed by trimming description to 924 chars with one-sentence pointer "v1.1.0 mandates a Step 0 freshness gate ... see SKILL body"
|
|
||||||
- [x] Saved feedback memory `skill_description_length_limit.md` so future me checks length after frontmatter edits
|
|
||||||
- [x] Wiki: appended "Freshness gate (v1.1.0)" subsection to `concepts/projects-meta-skills.md`; one entry in `log.md`
|
|
||||||
- [x] Closed in STATUS.md (🟢 done); next: commit + push + MCP round-trip close
|
|
||||||
|
|
||||||
## Notes
|
|
||||||
- User-supplied draft text for the skill (verbatim): _"Step 0 — Freshness gate. Always call mcp__projects-meta__meta_status first. If cache_age_minutes > 10 or errors.length > 0, run node ~/.local/projects-meta-mcp/dist/sync.js before any read. For shared-wiki writes (knowledge_ingest, knowledge_promote), additionally run git -C ~/projects/projects-wiki pull --ff-only — sha-based optimistic lock will reject your commit otherwise."_
|
|
||||||
- Trigger reason from user: "projects-meta — это шина между машинами. Юзер на ноуте может не знать, что на десктопе уже был коммит в shared wiki 5 минут назад. Без этого шага write-флоу ломается случайным образом, и баг трудно воспроизвести."
|
|
||||||
BIN
dist/setup-projects-meta.skill
vendored
BIN
dist/setup-projects-meta.skill
vendored
Binary file not shown.
BIN
dist/setup-tasks.skill
vendored
BIN
dist/setup-tasks.skill
vendored
Binary file not shown.
BIN
dist/setup-wiki.skill
vendored
BIN
dist/setup-wiki.skill
vendored
Binary file not shown.
BIN
dist/using-projects-meta.skill
vendored
BIN
dist/using-projects-meta.skill
vendored
Binary file not shown.
BIN
dist/using-tasks.skill
vendored
BIN
dist/using-tasks.skill
vendored
Binary file not shown.
BIN
dist/using-wiki.skill
vendored
BIN
dist/using-wiki.skill
vendored
Binary file not shown.
@@ -27,8 +27,8 @@ only place that touches user-level config or installs the server.
|
|||||||
|
|
||||||
| Path | Role |
|
| Path | Role |
|
||||||
|---|---|
|
|---|---|
|
||||||
| `~/.local/projects-meta-mcp/` | server repo (cloned from Gitea) |
|
| `~/projects/.common/lib/projects-meta-mcp/` | server repo (cloned from Gitea) |
|
||||||
| `~/.local/projects-meta-mcp/dist/server.js` | built stdio entry point |
|
| `~/projects/.common/lib/projects-meta-mcp/dist/server.js` | built stdio entry point |
|
||||||
| `~/.config/projects-mcp/auth.toml` | Gitea credentials (token-bearing) |
|
| `~/.config/projects-mcp/auth.toml` | Gitea credentials (token-bearing) |
|
||||||
| `~/.cache/projects-mcp/tasks.json` | aggregated tasks cache |
|
| `~/.cache/projects-mcp/tasks.json` | aggregated tasks cache |
|
||||||
| `~/projects/.wiki/` | shared wiki clone (Gitea repo `projects-wiki`, content in root) |
|
| `~/projects/.wiki/` | shared wiki clone (Gitea repo `projects-wiki`, content in root) |
|
||||||
@@ -67,7 +67,7 @@ Full procedure with shell snippets and templates lives in [`SKILL.md`](SKILL.md)
|
|||||||
|
|
||||||
1. Stop. Don't fix forward.
|
1. Stop. Don't fix forward.
|
||||||
2. `cp <file>.bak-<ts> <file>` for `~/.claude.json` and `~/.config/projects-mcp/auth.toml`.
|
2. `cp <file>.bak-<ts> <file>` for `~/.claude.json` and `~/.config/projects-mcp/auth.toml`.
|
||||||
3. Optional: `rm -rf ~/.local/projects-meta-mcp` and `rm -rf ~/.cache/projects-mcp`.
|
3. Optional: `rm -rf ~/projects/.common/lib/projects-meta-mcp` and `rm -rf ~/.cache/projects-mcp`.
|
||||||
Keep `~/projects/.wiki/` — it's a useful clone regardless of MCP state.
|
Keep `~/projects/.wiki/` — it's a useful clone regardless of MCP state.
|
||||||
4. Restart Claude Code.
|
4. Restart Claude Code.
|
||||||
5. Confirm `mcp__projects-meta__*` tools are gone (or back to the prior version).
|
5. Confirm `mcp__projects-meta__*` tools are gone (or back to the prior version).
|
||||||
|
|||||||
@@ -1,7 +1,7 @@
|
|||||||
---
|
---
|
||||||
name: setup-projects-meta
|
name: setup-projects-meta
|
||||||
version: 1.0.0
|
version: 1.0.0
|
||||||
description: Installs and configures the local `projects-meta-mcp` stdio server — clones the repo to `~/.local/projects-meta-mcp`, builds it, writes `~/.config/projects-mcp/auth.toml` with the user's Gitea token, clones the shared wiki to `~/projects/.wiki/` (content lives in root), and registers `mcpServers.projects-meta` in `~/.claude.json`. Use this skill when the user says "install projects-meta", "set up projects-meta", "configure projects-meta", "настрой projects-meta", "установи projects-meta", "projects-meta не работает", "projects-meta isn't working", or whenever the `mcp__projects-meta__*` tools are missing in a session that needs cross-project task aggregation or the shared Gitea wiki. Cross-platform — Windows / Linux / macOS. Mutates user-level config and writes secrets; pauses for confirmation before every write.
|
description: Installs and configures the local `projects-meta-mcp` stdio server — clones the repo to `~/projects/.common/lib/projects-meta-mcp`, builds it, writes `~/.config/projects-mcp/auth.toml` with the user's Gitea token, clones the shared wiki to `~/projects/.wiki/` (content lives in root), and registers `mcpServers.projects-meta` in `~/.claude.json`. Use this skill when the user says "install projects-meta", "set up projects-meta", "configure projects-meta", "настрой projects-meta", "установи projects-meta", "projects-meta не работает", "projects-meta isn't working", or whenever the `mcp__projects-meta__*` tools are missing in a session that needs cross-project task aggregation or the shared Gitea wiki. Cross-platform — Windows / Linux / macOS. Mutates user-level config and writes secrets; pauses for confirmation before every write.
|
||||||
---
|
---
|
||||||
|
|
||||||
# setup-projects-meta
|
# setup-projects-meta
|
||||||
@@ -35,7 +35,7 @@ The procedure clones a repo, writes `~/.config/projects-mcp/auth.toml` (carries
|
|||||||
- Confirm Claude Code is the current harness (need `mcpServers` registration in `~/.claude.json`).
|
- Confirm Claude Code is the current harness (need `mcpServers` registration in `~/.claude.json`).
|
||||||
- Confirm `git`, `node`, `npm` are on `PATH`. Node ≥ 18 (the server uses ES modules).
|
- Confirm `git`, `node`, `npm` are on `PATH`. Node ≥ 18 (the server uses ES modules).
|
||||||
- Confirm network reachability to `https://git.kzntsv.site` (the Gitea host). On HTTP 401/403 later, the token is dead — stop and ask for a new one.
|
- Confirm network reachability to `https://git.kzntsv.site` (the Gitea host). On HTTP 401/403 later, the token is dead — stop and ask for a new one.
|
||||||
- Pick paths: `~/.local/projects-meta-mcp`, `~/.config/projects-mcp/`, `~/.cache/projects-mcp/`, `~/projects/.wiki/` (shared wiki clone). POSIX-style `~/...` resolves correctly under git-bash on Windows.
|
- Pick paths: `~/projects/.common/lib/projects-meta-mcp`, `~/.config/projects-mcp/`, `~/.cache/projects-mcp/`, `~/projects/.wiki/` (shared wiki clone). POSIX-style `~/...` resolves correctly under git-bash on Windows.
|
||||||
|
|
||||||
### Phase 1 — Discovery (read-only)
|
### Phase 1 — Discovery (read-only)
|
||||||
|
|
||||||
@@ -49,9 +49,9 @@ Search, in order. Report only "found at <path>", never echo token values.
|
|||||||
|
|
||||||
The first hit wins. Capture internally for Phase 5; **never echo it in chat**.
|
The first hit wins. Capture internally for Phase 5; **never echo it in chat**.
|
||||||
|
|
||||||
**Repo install state.** Check whether `~/.local/projects-meta-mcp/.git` exists. If yes, `git -C ~/.local/projects-meta-mcp rev-parse HEAD` → record the SHA so Phase 4 can decide *clone* vs *pull*.
|
**Repo install state.** Check whether `~/projects/.common/lib/projects-meta-mcp/.git` exists. If yes, `git -C ~/projects/.common/lib/projects-meta-mcp rev-parse HEAD` → record the SHA so Phase 4 can decide *clone* vs *pull*.
|
||||||
|
|
||||||
**Build artifact.** Check `~/.local/projects-meta-mcp/dist/server.js`. If absent, Phase 4 will run `npm install && npm run build`.
|
**Build artifact.** Check `~/projects/.common/lib/projects-meta-mcp/dist/server.js`. If absent, Phase 4 will run `npm install && npm run build`.
|
||||||
|
|
||||||
**Shared wiki clone.** Check if `~/projects/.wiki/.git` exists and `origin` matches `https://git.kzntsv.site/OpeItcLoc03/projects-wiki(.git)?`. If non-matching `origin`, stop and ask — the user may have an unrelated wiki there.
|
**Shared wiki clone.** Check if `~/projects/.wiki/.git` exists and `origin` matches `https://git.kzntsv.site/OpeItcLoc03/projects-wiki(.git)?`. If non-matching `origin`, stop and ask — the user may have an unrelated wiki there.
|
||||||
|
|
||||||
@@ -65,7 +65,7 @@ Present a single-block plan to the user:
|
|||||||
|
|
||||||
```
|
```
|
||||||
Token: <found at <path> | NOT FOUND — will ask>
|
Token: <found at <path> | NOT FOUND — will ask>
|
||||||
Repo: <installed at ~/.local/projects-meta-mcp@<sha> | will clone>
|
Repo: <installed at ~/projects/.common/lib/projects-meta-mcp@<sha> | will clone>
|
||||||
Build artifact: <present | will run npm install && npm run build>
|
Build artifact: <present | will run npm install && npm run build>
|
||||||
Wiki clone: <present at ~/projects/.wiki | will clone | wrong remote — STOP>
|
Wiki clone: <present at ~/projects/.wiki | will clone | wrong remote — STOP>
|
||||||
MCP entry: <present in ~/.claude.json | will add | will fix path>
|
MCP entry: <present in ~/.claude.json | will add | will fix path>
|
||||||
@@ -92,12 +92,12 @@ Confirm both backups exist (when their source existed) before any further edit.
|
|||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Server
|
# Server
|
||||||
if [ -d ~/.local/projects-meta-mcp/.git ]; then
|
if [ -d ~/projects/.common/lib/projects-meta-mcp/.git ]; then
|
||||||
git -C ~/.local/projects-meta-mcp pull --ff-only
|
git -C ~/projects/.common/lib/projects-meta-mcp pull --ff-only
|
||||||
else
|
else
|
||||||
git clone https://git.kzntsv.site/OpeItcLoc03/projects-meta-mcp ~/.local/projects-meta-mcp
|
git clone https://git.kzntsv.site/OpeItcLoc03/projects-meta-mcp ~/projects/.common/lib/projects-meta-mcp
|
||||||
fi
|
fi
|
||||||
cd ~/.local/projects-meta-mcp
|
cd ~/projects/.common/lib/projects-meta-mcp
|
||||||
npm install
|
npm install
|
||||||
npm run build
|
npm run build
|
||||||
|
|
||||||
@@ -110,7 +110,7 @@ else
|
|||||||
fi
|
fi
|
||||||
```
|
```
|
||||||
|
|
||||||
Verify `~/.local/projects-meta-mcp/dist/server.js` exists after build. If not — abort, the build failed; ask the user to run `npm run build` manually and paste the output.
|
Verify `~/projects/.common/lib/projects-meta-mcp/dist/server.js` exists after build. If not — abort, the build failed; ask the user to run `npm run build` manually and paste the output.
|
||||||
|
|
||||||
### Phase 5 — Write `auth.toml`
|
### Phase 5 — Write `auth.toml`
|
||||||
|
|
||||||
@@ -173,7 +173,7 @@ Best-effort: call `mcp__projects-meta__meta_status`. If it returns a JSON blob w
|
|||||||
Then run a one-shot sync to populate the cache:
|
Then run a one-shot sync to populate the cache:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cd ~/.local/projects-meta-mcp
|
cd ~/projects/.common/lib/projects-meta-mcp
|
||||||
node dist/sync.js
|
node dist/sync.js
|
||||||
```
|
```
|
||||||
|
|
||||||
@@ -190,7 +190,7 @@ Tell the user:
|
|||||||
registration binds to a fresh stdio session.
|
registration binds to a fresh stdio session.
|
||||||
|
|
||||||
After restart:
|
After restart:
|
||||||
• mcp__projects-meta__* tools serve from ~/.local/projects-meta-mcp/dist/server.js
|
• mcp__projects-meta__* tools serve from ~/projects/.common/lib/projects-meta-mcp/dist/server.js
|
||||||
• Cache lives at ~/.cache/projects-mcp/tasks.json (refresh: node dist/sync.js)
|
• Cache lives at ~/.cache/projects-mcp/tasks.json (refresh: node dist/sync.js)
|
||||||
• Shared wiki clone at ~/projects/.wiki/ — `git -C ~/projects/.wiki pull --ff-only` for fresh anchors
|
• Shared wiki clone at ~/projects/.wiki/ — `git -C ~/projects/.wiki pull --ff-only` for fresh anchors
|
||||||
• Backups saved at ~/.claude.json.bak-<ts> (and auth.toml.bak-<ts> if it existed before)
|
• Backups saved at ~/.claude.json.bak-<ts> (and auth.toml.bak-<ts> if it existed before)
|
||||||
@@ -206,7 +206,7 @@ If a problem surfaces (now or after restart):
|
|||||||
1. Stop. Don't try to fix forward.
|
1. Stop. Don't try to fix forward.
|
||||||
2. Find the most recent `.bak-YYYYMMDD-HHMMSS` next to `~/.claude.json` (and `~/.config/projects-mcp/auth.toml` if applicable).
|
2. Find the most recent `.bak-YYYYMMDD-HHMMSS` next to `~/.claude.json` (and `~/.config/projects-mcp/auth.toml` if applicable).
|
||||||
3. `cp <file>.bak-<ts> <file>` for each.
|
3. `cp <file>.bak-<ts> <file>` for each.
|
||||||
4. Optional: `rm -rf ~/.local/projects-meta-mcp` and `rm -rf ~/.cache/projects-mcp`. Keep `~/projects/.wiki/` — it's a useful clone regardless of MCP state.
|
4. Optional: `rm -rf ~/projects/.common/lib/projects-meta-mcp` and `rm -rf ~/.cache/projects-mcp`. Keep `~/projects/.wiki/` — it's a useful clone regardless of MCP state.
|
||||||
5. Restart Claude Code.
|
5. Restart Claude Code.
|
||||||
6. Confirm `mcp__projects-meta__*` is gone (or back to the pre-existing version).
|
6. Confirm `mcp__projects-meta__*` is gone (or back to the pre-existing version).
|
||||||
7. Report what went wrong so we can fix the procedure.
|
7. Report what went wrong so we can fix the procedure.
|
||||||
|
|||||||
@@ -59,7 +59,7 @@ Before **any** `tasks_*` or `knowledge_*` call:
|
|||||||
|
|
||||||
1. `mcp__projects-meta__meta_status` — probe cache age + errors.
|
1. `mcp__projects-meta__meta_status` — probe cache age + errors.
|
||||||
2. If `cache_age_minutes` > 10 OR `errors_count` > 0 →
|
2. If `cache_age_minutes` > 10 OR `errors_count` > 0 →
|
||||||
`node ~/.local/projects-meta-mcp/dist/sync.js`.
|
`node ~/projects/.common/lib/projects-meta-mcp/dist/sync.js`.
|
||||||
3. For shared-wiki **writes** (`knowledge_ingest`, `knowledge_promote`) →
|
3. For shared-wiki **writes** (`knowledge_ingest`, `knowledge_promote`) →
|
||||||
**also** `git -C ~/projects/projects-wiki pull --ff-only`. Unconditional.
|
**also** `git -C ~/projects/projects-wiki pull --ff-only`. Unconditional.
|
||||||
The MCP server uses sha-based optimistic locking on the wiki repo;
|
The MCP server uses sha-based optimistic locking on the wiki repo;
|
||||||
@@ -134,7 +134,7 @@ from `auth.toml`).
|
|||||||
two different stores. `using-wiki` operates on the local one;
|
two different stores. `using-wiki` operates on the local one;
|
||||||
`using-projects-meta` queries / ingests the shared one.
|
`using-projects-meta` queries / ingests the shared one.
|
||||||
- **Acting on stale `tasks_aggregate`.** If `meta_status.age_seconds` > 3600,
|
- **Acting on stale `tasks_aggregate`.** If `meta_status.age_seconds` > 3600,
|
||||||
either run `node dist/sync.js` (in `~/.local/projects-meta-mcp`) or warn the
|
either run `node dist/sync.js` (in `~/projects/.common/lib/projects-meta-mcp`) or warn the
|
||||||
user about staleness.
|
user about staleness.
|
||||||
- **Vague `knowledge_search` queries.** "auth" returns noise. Multi-word,
|
- **Vague `knowledge_search` queries.** "auth" returns noise. Multi-word,
|
||||||
specific queries return targeted snippets.
|
specific queries return targeted snippets.
|
||||||
|
|||||||
@@ -65,8 +65,8 @@ Use MCP only for **other** projects, **other** machines, or **shared** wiki cont
|
|||||||
|
|
||||||
2. Branch on cache freshness:
|
2. Branch on cache freshness:
|
||||||
• If cache_age_minutes > 10 OR errors_count > 0:
|
• If cache_age_minutes > 10 OR errors_count > 0:
|
||||||
run `node ~/.local/projects-meta-mcp/dist/sync.js`
|
run `node ~/projects/.common/lib/projects-meta-mcp/dist/sync.js`
|
||||||
(or `npm run sync` from ~/.local/projects-meta-mcp).
|
(or `npm run sync` from ~/projects/.common/lib/projects-meta-mcp).
|
||||||
• Else: cache is fresh enough — skip sync, no need to hit the network.
|
• Else: cache is fresh enough — skip sync, no need to hit the network.
|
||||||
|
|
||||||
3. For shared-wiki WRITES (knowledge_ingest, knowledge_promote):
|
3. For shared-wiki WRITES (knowledge_ingest, knowledge_promote):
|
||||||
@@ -221,7 +221,7 @@ User: "close `[projects-meta-skills]` in claude-skills"
|
|||||||
| Reading current project's tasks via `tasks_get` instead of disk | Read `.tasks/STATUS.md` directly. MCP is for *other* projects. |
|
| Reading current project's tasks via `tasks_get` instead of disk | Read `.tasks/STATUS.md` directly. MCP is for *other* projects. |
|
||||||
| Inlining `confirm: true` on the first mutation call | Always preview first; show user; only then `confirm: true`. |
|
| Inlining `confirm: true` on the first mutation call | Always preview first; show user; only then `confirm: true`. |
|
||||||
| Using `knowledge_search` for the project's own wiki | The shared wiki is a separate Gitea repo. Local `.wiki/` is in cwd. |
|
| Using `knowledge_search` for the project's own wiki | The shared wiki is a separate Gitea repo. Local `.wiki/` is in cwd. |
|
||||||
| Acting on a stale `tasks_aggregate` without checking `meta_status` | Step 0 — Freshness gate is mandatory. If `cache_age_minutes` > 10 (or errors > 0), run `node ~/.local/projects-meta-mcp/dist/sync.js` first. |
|
| Acting on a stale `tasks_aggregate` without checking `meta_status` | Step 0 — Freshness gate is mandatory. If `cache_age_minutes` > 10 (or errors > 0), run `node ~/projects/.common/lib/projects-meta-mcp/dist/sync.js` first. |
|
||||||
| Skipping `git -C ~/projects/projects-wiki pull` before `knowledge_ingest` / `knowledge_promote` | sha-based optimistic lock will reject the commit (422) and the failure is opaque. Pull is unconditional for shared-wiki writes — fast-forward is a no-op when current. |
|
| Skipping `git -C ~/projects/projects-wiki pull` before `knowledge_ingest` / `knowledge_promote` | sha-based optimistic lock will reject the commit (422) and the failure is opaque. Pull is unconditional for shared-wiki writes — fast-forward is a no-op when current. |
|
||||||
| Treating sync 401/403 as "MCP is fine, the page just doesn't exist yet" | 401/403 means the Gitea token is dead. Stop, tell the user to rotate `gitea_token` in `~/.config/projects-mcp/auth.toml`. Never guess on stale data. |
|
| Treating sync 401/403 as "MCP is fine, the page just doesn't exist yet" | 401/403 means the Gitea token is dead. Stop, tell the user to rotate `gitea_token` in `~/.config/projects-mcp/auth.toml`. Never guess on stale data. |
|
||||||
| Calling `knowledge_ingest` with the wrong `type` | `type` must be one of `entities` / `concepts` / `packages` / `sources` / `raw`. Mis-typed pages land in the wrong section and break `index.md`. |
|
| Calling `knowledge_ingest` with the wrong `type` | `type` must be one of `entities` / `concepts` / `packages` / `sources` / `raw`. Mis-typed pages land in the wrong section and break `index.md`. |
|
||||||
|
|||||||
Reference in New Issue
Block a user