chore(1459): убраны mappa-vitya-* из skills-репо — перенесены в victor/mappa-vitya-skills
- удалены skills/mappa-vitya-brainstorming + mappa-vitya-project-discipline - README: убрана строка provenance mappa-vitya-brainstorming - project-bootstrap: ссылки на mappa-vitya-project-discipline → victor/mappa-vitya-skills - правило уведомлений (.admin) уже зафиксировано в целевом репо (3b4d51c)
This commit is contained in:
@@ -114,7 +114,6 @@ an explicit `adapted-from` marker in its frontmatter.
|
||||
| `find-skills` | `adapted-from: vercel-labs/skills @ c6f69c6` (MIT) — vendored copy |
|
||||
| `grilling` | `adapted-from: mattpocock/skills @ 84fdeffd` (MIT) — family collapsed to one skill (pi hides `disable-model-invocation` wrappers) |
|
||||
| `brainstorming` | `adapted-from: obra/superpowers @ 6.2.0` (MIT) — divergent phase, visual-companion dropped |
|
||||
| `mappa-vitya-brainstorming` | `author: ours` — brainstorm METHODOLOGY for a mappa zone (capture in mappa entity, maturity by criterion, spec → wiki, paired+umbrella review, ask who implements, notify); promotion mechanics delegated to `mappa-brainstorm-promote` |
|
||||
| `diagnosing-bugs` | `adapted-from: mattpocock/skills @ 84fdeffd` (MIT) + superpowers 6.2.0 concepts (Iron Law, red flags) |
|
||||
| `loop-me` | `adapted-from: mattpocock/skills @ 84fdeffd` (MIT) — workflow-spec design gate |
|
||||
| `review-kit-pi-method` | `author: ours` — pi-native spawn for clean-context review subagents |
|
||||
|
||||
@@ -1,163 +0,0 @@
|
||||
---
|
||||
name: mappa-vitya-brainstorming
|
||||
author: ours
|
||||
version: 0.1.0
|
||||
description: >
|
||||
The brainstorm METHODOLOGY (the behavior layer) for a mappa knowledge zone —
|
||||
runs a storm, keeps its running-record buffer, judges MATURITY, and routes
|
||||
the matured result (spec → wiki concept, tasks, reviews). The mappa promotion
|
||||
MECHANICS are delegated to mappa-brainstorm-promote. Use when the user opens
|
||||
a brainstorm or asks whether a storm is mature enough to persist. Triggers:
|
||||
«забрендшторми», «поштормим», «накидай идеи», «что думаешь про идею»,
|
||||
«разложи куда что», «когда шторм зрелый», "brainstorm this",
|
||||
"help me think this through", "run the storm". NOT for: sharpening a finished
|
||||
plan (→ grilling), a single recommendation (→ recommend-dont-menu), or the
|
||||
mappa promotion mechanics (→ mappa-brainstorm-promote).
|
||||
---
|
||||
|
||||
# mappa-vitya-brainstorming
|
||||
|
||||
**This is the vitya-flavored brainstorm *methodology*.** It tells you how to
|
||||
run a storm in a mappa zone and where the matured output goes. It does NOT
|
||||
implement the mappa promotion mechanics — that is `mappa-brainstorm-promote`.
|
||||
|
||||
Run a brainstorm **anywhere**, in **any project**, by **any agent**. This is not
|
||||
boss-zone-only. You (the agent driving the storm) own the method; promotion is
|
||||
a separate mechanical step you delegate to the promote skill.
|
||||
|
||||
A storm produces impl tasks → this skill also covers the review routing. A
|
||||
storm that produces **zero impl tasks** (a research/decision-only storm) is
|
||||
mature when the decisions are distilled into a wiki concept and no review
|
||||
umbrella is created — the criterion holds vacuously, no tasks to review.
|
||||
|
||||
**Boundary with the promote skill:** this skill ends at "I have judged
|
||||
maturity and know the routing shape — which decisions become a spec, which
|
||||
become tasks, how many reviews". It passes a **routing decision** to
|
||||
`mappa-brainstorm-promote`, NOT a question of whether to persist.
|
||||
|
||||
## When to use
|
||||
|
||||
- User opens a brainstorm: «забрендшторми», «накидай идеи», «что думаешь про
|
||||
идею», «поштормим», "brainstorm this", "run the storm".
|
||||
- A storm is running and you must decide whether it's mature enough to persist.
|
||||
- You must route the matured result into mappa (spec → wiki, tasks + reviews).
|
||||
|
||||
**NOT for:** sharpening a finished plan (→ grilling), single recommendation
|
||||
(→ recommend-dont-menu), or the actual mappa promotion mechanics (→
|
||||
`mappa-brainstorm-promote`).
|
||||
|
||||
## Quick reference
|
||||
|
||||
| Decision | Answer |
|
||||
|---|---|
|
||||
| Where does the buffer live | A mappa `brainstorm` entity (status=buffer). NOT a file. |
|
||||
| When is a storm mature | The buffer-completion criterion, NOT a gut feel. |
|
||||
| Where does the spec/decisions go | A mappa **wiki concept**. Before any wiki work — run `mappa-knowledge` first. |
|
||||
| Multiple impl tasks | **ИЛИ**: единичная таска → парная `<slug>-review`; кластер из одного шторма → зонтичный `<topic>-review` (парные НЕ создаются). Blocked, non-implementer. |
|
||||
| Who implements | ASK who implements (you are not automatically it). Boss does not implement (Rule 10). |
|
||||
| Who notifies | Send an `inbox_send` letter to every affected project. |
|
||||
| Zero-impl storm | Mature when decisions are distilled into a wiki concept; NO review umbrella (criterion holds vacuously). |
|
||||
|
||||
## Core method
|
||||
|
||||
**1. Capture the buffer in mappa, not in a file.**
|
||||
Start the storm as a mappa `brainstorm` entity (status=buffer). It is the
|
||||
running record. Update it after each significant decision, not in batches — a
|
||||
crash-safe append beats token savings. File-based buffers (`.brainstorm/`,
|
||||
`notes/*.md`) are legacy; the file channel is closed.
|
||||
|
||||
**2. Maturity is a criterion, not a feeling.**
|
||||
Do not persist on "it feels done". The storm is mature to persist when the
|
||||
buffer-completion criterion holds: all action-items have been raised as tasks,
|
||||
and all those tasks are done (including the review task — paired or umbrella). Decide this from
|
||||
the criterion — derived from the graph, not judged by hand.
|
||||
|
||||
**3. Distill into decisions, keep the record.**
|
||||
The buffer records **decisions** (what was decided and why), not just "we
|
||||
talked". Refs (`[[...]]`) link entities. The value is the decision trail, not
|
||||
prose volume.
|
||||
|
||||
**4. Specs/knowledge → mappa wiki concepts.**
|
||||
Matured conclusions (the "what we decided and why") become a **mappa wiki
|
||||
concept** (`wiki_create`). It is a formal enough spec: context → decisions →
|
||||
rationale → non-goals → open questions, so intent is recoverable and tasks can
|
||||
reference it. Domain knowledge goes to the target project's wiki; workshop-meta
|
||||
to the `.workshop` wiki entity. **Before any wiki work — run `mappa-knowledge`
|
||||
first** (Rule 6), it loads the project's AGENTS entity and the read/ingest
|
||||
contract.
|
||||
|
||||
**5. Review is a separate, non-implementer role.**
|
||||
Review routing (оператор 2026-08-28): **парные review ИЛИ зонтик** (не BOTH).
|
||||
- **Единичная импл-таска** из шторма → парная `<slug>-review` (status=blocked, blocker=impl-ref), без зонтика.
|
||||
- **Кластер тасок** из одного шторма → зонтичный `<topic>-review` на весь кластер (status=blocked, blocker=impl-slugs); парные на каждую таску НЕ создаются (иначе двойное ревью одного и того же).
|
||||
|
||||
Reviewer is the next session in the target, **not the implementer** — this
|
||||
fights the "I just wrote it" bias. You (the brainstorming agent) generate the
|
||||
review tasks; you do NOT do the code review yourself. The review is done only
|
||||
when its reviewer confirms — the storm is not mature until the review
|
||||
(`<slug>-review` ИЛИ `<topic>-review`) is resolved, not merely created.
|
||||
|
||||
**6. Ask who implements. Do not assume it's you.**
|
||||
Brainstorms run anywhere by any agent. The implementer is not automatically the
|
||||
storming agent. If the project is the boss zone (`.workshop`), the boss does NOT
|
||||
implement (Rule 10) — it distills and routes via `task_create` to a target
|
||||
project. In other projects the storming agent may implement, but ASK rather
|
||||
than assume.
|
||||
|
||||
**7. Notify affected projects with a letter.**
|
||||
A task on a board does not ping a live session. After raising tasks, send an
|
||||
`inbox_send` letter to every affected project (all except yourself — a
|
||||
self-copy is not a notification). This is the required ping.
|
||||
|
||||
## Where the mappa promotion happens (delegate, don't repeat)
|
||||
|
||||
The **mechanics** — `wiki_create` / `brainstorm_promote`, `task_create`,
|
||||
creating review pairs/umbrella, sending the covering letter, adding the final
|
||||
buffer entry — live in **`mappa-brainstorm-promote`**. This skill does NOT
|
||||
duplicate those steps; it points to the promote skill for the actual
|
||||
persistence/promotion.
|
||||
|
||||
**Boundary:** you (the brainstorming agent) run the storm and decide maturity
|
||||
and routing (what becomes a spec, what becomes tasks, how many reviews). The
|
||||
promote skill executes the mappa write/promotion.
|
||||
|
||||
## Common rationalizations (excuse → reality)
|
||||
|
||||
| Excuse | Reality |
|
||||
|---|---|
|
||||
| "I'll just jot notes in a markdown file" | Buffer must be a mappa brainstorm entity; the file channel is closed. |
|
||||
| "It feels done, let's write it up" | Maturity is the completion criterion, not a feeling. |
|
||||
| "The spec can live in docs/ for now" | Spec goes to a mappa wiki concept; before wiki — run `mappa-knowledge`. |
|
||||
| "I'll review my own tasks, then hand to the user" | Review is a separate non-implementer role; парная ИЛИ зонтик (не BOTH). |
|
||||
| "I'm the coding agent, I'll just implement it" | Ask who implements; in the boss zone the boss does not implement. |
|
||||
| "I'll note the impact in the spec, no need to ping" | Notify every affected project with an `inbox_send` letter. |
|
||||
|
||||
## Red flags (all = STOP and re-orient)
|
||||
|
||||
- You created a `.brainstorm/` or `notes/*.md` file instead of a mappa entity.
|
||||
- You are persisting because "it feels mature", not by the completion criterion.
|
||||
- You are about to write the spec to a repo file rather than a mappa wiki concept.
|
||||
- You are reviewing your own implementation (or the user reviewing it) instead
|
||||
of a separate non-implementer reviewer.
|
||||
- You assume you are the implementer for a boss-zone storm.
|
||||
- You are skipping the `inbox_send` notification to affected projects.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Does NOT stress-test a finished plan (→ grilling).
|
||||
- Does NOT give a single recommendation (→ recommend-dont-menu).
|
||||
- Does NOT execute the mappa promotion mechanics (→ `mappa-brainstorm-promote`).
|
||||
- Does NOT cover code-discipline / git / versions / push (→ `project-discipline`
|
||||
/ `mappa-vitya-project-discipline`).
|
||||
|
||||
## Cross-agent applicability
|
||||
|
||||
Behavior methodology with a mappa-media dependency. The mappa tool names are
|
||||
concrete (this zone runs on mappa); the METHOD (capture in a durable record,
|
||||
maturity by criterion, spec to the durable knowledge store, separate reviewer,
|
||||
ask who implements, notify affected) transfers to any mappa-based zone. On a
|
||||
non-mappa setup, substitute the corresponding knowledge channels.
|
||||
|
||||
**`mappa-knowledge` is a mandatory precursor before any wiki work** (Rule 6):
|
||||
it loads the project's AGENTS entity and the read/ingest contract. Never write
|
||||
a wiki concept without running it first.
|
||||
@@ -1,59 +0,0 @@
|
||||
# mappa-vitya-project-discipline
|
||||
|
||||
Vitya-flavored cross-project discipline policy skill for a mappa knowledge zone.
|
||||
Codifies the five work rules (project-canon via mappa, master-only, semver,
|
||||
push) PLUS four mappa-canon rules (rg-only search, live-verify after reload,
|
||||
knowledge-first, durable-knowledge-to-wiki).
|
||||
|
||||
## When it triggers
|
||||
|
||||
- **Session start** — when `AGENTS.md` contains the line
|
||||
`follow mappa-vitya project discipline` (inserted by `mappa-bootstrap`, which
|
||||
selects the project's methodology flavor).
|
||||
- **In-chat** — when the user says "use project discipline", "соблюди
|
||||
дисциплину", "проектные правила", "follow project discipline", or close
|
||||
variants.
|
||||
|
||||
## The rules
|
||||
|
||||
1. **Project canon is a mappa wiki entity, not files.** Read the project's
|
||||
`AGENTS` entity (`wiki_get(project,'AGENTS')`), NOT `.wiki/CLAUDE.md` /
|
||||
`.tasks/` (file channel closed). Before any wiki work — run `mappa-knowledge`
|
||||
first.
|
||||
2. **Master-only.** All work on `master` (or `main`). No feature branches
|
||||
without explicit user approval.
|
||||
3. **Semver discipline.** Bump `version:` in `SKILL.md` / `package.json` /
|
||||
`pyproject.toml` on every edit per MAJOR / MINOR / PATCH; record in commit
|
||||
message; rebuild `dist/` artifacts after.
|
||||
4. **Push freely by default.** No confirmation needed for push; a local push
|
||||
gate (`push gate: ask` in AGENTS entity, or explicit operator word)
|
||||
overrides per project. Force / delete / non-ff push always asks.
|
||||
5. **Transit-zone / brainstorm workspaces (mappa channel).** Brainstorm
|
||||
artifacts go to a mappa brainstorm entity, not `.brainstorm/*.md`. Only
|
||||
promote to a wiki concept when the user explicitly directs.
|
||||
|
||||
## Mappa-canon rules
|
||||
|
||||
- **Rule G — rg-only search.** Never walk node_modules/dist/build with
|
||||
`grep -r`/`find`/`ag`/`ack`. Use `rg` (gitignore-aware); never `rg --no-ignore`.
|
||||
- **Rule K — knowledge-first.** Run `mappa-knowledge` before any wiki work.
|
||||
- **Rule L — live-verify after reload.** Infra changes verified in a live
|
||||
interactive session, not headless.
|
||||
- **Rule D — durable knowledge to mappa wiki.** Never `memory/` / local files;
|
||||
go to a mappa wiki entity.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- `mappa` MCP server available (`mcp__mappa__*`) to read the canon.
|
||||
- `mappa-knowledge` skill installed.
|
||||
- Methodology flavor selected by `mappa-bootstrap` (the source of the
|
||||
`follow mappa-vitya project discipline` trigger line).
|
||||
|
||||
## Related
|
||||
|
||||
- `mappa-bootstrap` — picks the methodology flavor per project and inserts the
|
||||
trigger line.
|
||||
- `project-bootstrap` — writes the project scaffold (removed the legacy
|
||||
`follow project discipline` trigger; the generic skill was replaced by the
|
||||
per-flavor `mappa-vitya-project-discipline`).
|
||||
- `mappa-vitya-brainstorming` — the brainstorm METHODOLOGY for a mappa zone.
|
||||
@@ -1,264 +0,0 @@
|
||||
---
|
||||
name: mappa-vitya-project-discipline
|
||||
author: ours
|
||||
version: 1.0.0
|
||||
description: >
|
||||
The vitya-flavored cross-project discipline for a mappa knowledge zone —
|
||||
codifies the work rules (project-canon via mappa, master-only, semver, push)
|
||||
PLUS the four mappa-canon rules (rg-only search, live-verify after reload,
|
||||
knowledge-first, durable-knowledge-to-wiki). The mappa METHODOLOGY for a
|
||||
project is selected by mappa-bootstrap, not hardcoded here. Use when the user
|
||||
says "follow project discipline", "соблюди дисциплину", "проектные правила",
|
||||
"что у меня по правилам?", "use project discipline", or when AGENTS.md
|
||||
contains "follow mappa-vitya project discipline". NOT for: the method SELECTION
|
||||
itself (→ mappa-bootstrap), a project's own AGENTS.md content (→ project-bootstrap).
|
||||
---
|
||||
|
||||
# mappa-vitya-project-discipline
|
||||
|
||||
**This is the vitya-flavored cross-project *discipline* skill.** It tells you
|
||||
the work rules to apply in a project on a mappa-based setup. It is a
|
||||
policy document — the agent reads it and behaves; it takes no actions and has
|
||||
no external side-effects.
|
||||
|
||||
Run the discipline **anywhere**, in **any project**, by **any agent**. The
|
||||
methodology flavor is chosen per-project by `mappa-bootstrap` (this is the
|
||||
`mappa-vitya-*` flavor). The skill itself does NOT select or swap methodology —
|
||||
that is `mappa-bootstrap`'s job.
|
||||
|
||||
**Boundary with `mappa-bootstrap`:** this skill defines WHAT the discipline is
|
||||
for the vitya flavor. `mappa-bootstrap` decides WHETHER/WHICH methodology a
|
||||
project uses (by detecting methodology traces in AGENTS.md and installing /
|
||||
delivering the matching skills). The trigger that activates this skill —
|
||||
`follow mappa-vitya project discipline` — is inserted by `mappa-bootstrap`, not
|
||||
baked into a project by hand as canon rules here.
|
||||
|
||||
## When to use
|
||||
|
||||
- AGENTS.md contains `follow mappa-vitya project discipline` — apply the rules
|
||||
for the rest of the session.
|
||||
- User says "use project discipline", "соблюди дисциплину", "проектные
|
||||
правила", "что у меня по правилам?", "follow project discipline", or asks
|
||||
about/applying the rules.
|
||||
|
||||
**NOT for:** the methodology selection (→ `mappa-bootstrap`), writing a
|
||||
project's own AGENTS.md content (→ `project-bootstrap`), or the mappa
|
||||
brainstorm/promotion method (→ `mappa-vitya-brainstorming`).
|
||||
|
||||
## The rules
|
||||
|
||||
### Rule 1 — Project canon is a mappa wiki entity, not files
|
||||
|
||||
Before applying default behavior, read the project's canon from **mappa**, not
|
||||
from files. On a mappa-based setup the file channel (`.wiki/CLAUDE.md`,
|
||||
`.tasks/`, `.brainstorm/`) is **closed** — the canonical contract lives as
|
||||
mappa entities.
|
||||
|
||||
Read order:
|
||||
|
||||
1. The project's mappa **wiki entity `AGENTS`** — `wiki_get(project, 'AGENTS')`
|
||||
(or for the boss-zone, `wiki_get('.workshop','AGENTS')`). This is the
|
||||
project's canonical contract.
|
||||
2. The mappa **handoff** entity (session-start contract) and **inbox** letters.
|
||||
3. The workspace/zone contract via `.workshop` AGENTS entity where relevant.
|
||||
|
||||
Any path, format, or workflow explicitly stated in the project's AGENTS entity
|
||||
**overrides this skill's default.** No file-based `.wiki/CLAUDE.md` /
|
||||
`.tasks/` lookups — those are legacy/stubs («не читать, не править»).
|
||||
|
||||
**Mandatory precursor:** before ANY wiki work — run `mappa-knowledge` first. It
|
||||
loads the project's AGENTS entity and the read/ingest contract. Never write a
|
||||
wiki concept without running it first (this is also mappa-canon rule **K**).
|
||||
|
||||
Concrete consequences:
|
||||
|
||||
- **Specs / design decisions** → a mappa **wiki concept** (`wiki_create`).
|
||||
- **Tasks / implementation plans** → mappa **task entities** (`task_create`).
|
||||
- **Brainstorm buffers** → mappa **brainstorm entities** (`brainstorm_create`),
|
||||
not `.brainstorm/*.md` files.
|
||||
- If no convention is stated — fall back to the skill default.
|
||||
|
||||
### Rule 2 — Master-only
|
||||
|
||||
All work happens on the repo's main integration branch — usually `master`, but
|
||||
if a project uses `main`, treat `main` as equivalent.
|
||||
|
||||
- No `git checkout -b feature/foo` for solo work.
|
||||
- Sync with remote: `git pull --ff-only` or `git pull --rebase`. **No merge
|
||||
commits** for solo work.
|
||||
- If a task genuinely requires isolation (large experiment, risky refactor with
|
||||
rollback potential, multi-day work with intermediate WIP commits) — **ask**
|
||||
the user: "this needs its own branch, ok?" — and wait for explicit approval.
|
||||
Without approval, work continues on master.
|
||||
- If the agent finds itself on a non-main branch or in detached HEAD — report
|
||||
it and ask whether to return to master before working.
|
||||
|
||||
### Rule 3 — Versioning discipline
|
||||
|
||||
When editing any artifact with a semver field, **bump the version before
|
||||
committing** per:
|
||||
|
||||
- **MAJOR** (`X+1.0.0`) — breaks the contract. Renames, removed triggers, layout
|
||||
changes, removed public functions, breaking API change.
|
||||
- **MINOR** (`X.Y+1.0`) — adds capability without breaking. New trigger, new
|
||||
optional step, new public function.
|
||||
- **PATCH** (`X.Y.Z+1`) — wording / clarity / typo fixes with no behavior change.
|
||||
|
||||
The bump is recorded in the commit message: `feat(<artifact>): … [vX.Y.Z]` or
|
||||
whatever convention the project uses (see Rule 1).
|
||||
|
||||
**Applies to:** `skills/<name>/SKILL.md` (`version:` in frontmatter),
|
||||
`package.json`, `pyproject.toml`, `Cargo.toml`, and any other semver field.
|
||||
|
||||
**If the artifact is packaged** as `dist/<name>.skill` — **rebuild** the package
|
||||
in the same or the next commit. Forgotten dist artifacts are a common cause of
|
||||
deploying stale binaries.
|
||||
|
||||
**First edit of an unversioned artifact** that COULD have a semver field — **add**
|
||||
`version: 0.1.0` before committing; do not bump anything.
|
||||
|
||||
### Rule 4 — Push freely, gate only where a local gate exists
|
||||
|
||||
**Default: push freely.** An ordinary fast-forward `git push` to the configured
|
||||
upstream needs no per-push confirmation. No ask-before-push mode by default.
|
||||
|
||||
**Push gate** (replaces the free-push default for a specific project). A push
|
||||
gate makes every push require confirmation — it is set up ONE of two ways:
|
||||
|
||||
- **On the record** — the project's AGENTS.md / AGENTS entity declares a push
|
||||
gate (e.g. `push gate: ask`); it applies persistently for that project.
|
||||
- **Explicitly, by the operator, in the session** — the operator says "push
|
||||
gate" / "спрашивай перед пушем"; it applies for the rest of that session OR
|
||||
until explicitly lifted.
|
||||
|
||||
Either way, when a gate is active, EVERY push to that project asks first.
|
||||
|
||||
**Always ask:** `git push --force` / `--force-with-lease`; branch deletion;
|
||||
push to a remote/branch other than the current tracked upstream; push to the
|
||||
main branch that would require non-fast-forward.
|
||||
|
||||
**What counts as "push":** only `git push` family commands. Local commits,
|
||||
`git stash push`, etc. are not push.
|
||||
|
||||
### Rule 5 — Transit-zone / brainstorm workspaces (mappa channel)
|
||||
|
||||
Some workspaces are **transit zones** — discussion areas where brainstorm
|
||||
artifacts are NOT auto-promoted to project wikis. On a mappa setup the default
|
||||
destination is the mappa brainstorm entity, not a file.
|
||||
|
||||
**Default destination for brainstorm artifacts:**
|
||||
- **In-progress brainstorm outputs** → a mappa **brainstorm entity**
|
||||
(status=buffer). `.brainstorm/*.md` files are legacy; the file channel is
|
||||
closed.
|
||||
- **Mature, cross-cutting outputs** → mappa **wiki concept** (via
|
||||
`wiki_create`) — **only** when the user explicitly directs this.
|
||||
|
||||
**Agent must NOT auto-promote** brainstorm artifacts to wikis by analogy with
|
||||
Rule 1. The convergence-moment (move from buffer to permanent wiki) is a user
|
||||
decision, not an automatic action.
|
||||
|
||||
**When in doubt:** ask the user "this goes to a mappa brainstorm entity, or
|
||||
should I promote it to a wiki concept?" rather than assuming.
|
||||
|
||||
## Mappa-canon rules
|
||||
|
||||
These four rules are the mappa-canon discipline for any mappa-based zone. They
|
||||
apply in addition to the five above.
|
||||
|
||||
### Rule G — rg-only search (never walk node_modules/dist/build)
|
||||
|
||||
⛔ Never walk `node_modules/`, `dist/`, `build/`, `.nuxt/`, or any parent tree
|
||||
containing them with non-gitignore-aware search tools.
|
||||
|
||||
- Use **`rg`** (gitignore-aware). NEVER `rg --no-ignore` / `-u` — those bypass
|
||||
the ignore protection and walk node_modules again.
|
||||
- Also no `grep -r` / `-R` / `--recursive`, `ag`, `ack`, `find … -exec grep`.
|
||||
- `grep --include` filters result file names, NOT directory traversal — it still
|
||||
walks every node_modules entry. `| grep -v node_modules` filters after the
|
||||
walk, doesn't save you.
|
||||
|
||||
Rationale: measured 3701s (grep walk of a projects tree) vs 0s (rg) —
|
||||
2026-08-26 incident, task:1233.
|
||||
|
||||
### Rule K — knowledge-first (mappa-knowledge before any wiki)
|
||||
|
||||
Before ANY work with a project's wiki — run the `mappa-knowledge` skill FIRST,
|
||||
not after the first step. It loads the project's AGENTS entity and the
|
||||
read/ingest contract. Never write a wiki concept, ingest, or query without
|
||||
running it first. (Violation noted twice in one session — fixed by rule, not
|
||||
excuses.)
|
||||
|
||||
### Rule L — live-verify after reload
|
||||
|
||||
Infrastructure changes (MCP wiring, adapters, configs, bridges) must be
|
||||
verified in a **live interactive session after reload**, not just by headless
|
||||
checks. "Fixed, verified headless" is NOT enough — precedent: the
|
||||
`mappa-http-adapter` (2026-08-25) passed headless but failed real use.
|
||||
|
||||
After an infra change, minimally: reload the configuration + make a real
|
||||
tool call in a live session.
|
||||
|
||||
### Rule D — durable knowledge → mappa wiki, never memory/local files
|
||||
|
||||
Durable knowledge (domain, ops, methodology) goes to a **mappa wiki entity**,
|
||||
NOT to local per-project memory (`~/.claude/.../memory/`) or repo files. Memory
|
||||
is not queryable by peer sessions, not graph-linked, and is lost. If you catch
|
||||
yourself writing durable knowledge to `memory/` or a local file — stop, redirect
|
||||
to a mappa wiki entity (domain → target project's wiki; workshop-meta →
|
||||
`.workshop` wiki entity). User: "все важное писать в вики" (2026-06-18).
|
||||
|
||||
## Quick reference
|
||||
|
||||
| Decision | Answer |
|
||||
|---|---|
|
||||
| Where is the project canon | mappa wiki entity `AGENTS` — NOT `.wiki/CLAUDE.md` / `.tasks/`. |
|
||||
| Before any wiki work | Run `mappa-knowledge` first (Rule K). |
|
||||
| Where do specs/design go | mappa wiki concept (`wiki_create`). |
|
||||
| Where do tasks go | mappa task entities (`task_create`). |
|
||||
| Where do brainstorm buffers live | mappa brainstorm entity — NOT `.brainstorm/*.md`. |
|
||||
| Search a codebase | `rg` only — never `grep -r`/`find` over node_modules/dist (Rule G). |
|
||||
| Infra change verification | Live session after reload, not headless (Rule L). |
|
||||
| Durable knowledge | mappa wiki, never `memory/` / local files (Rule D). |
|
||||
| Method flavor / selection | `mappa-bootstrap` selects; this skill only defines the vitya rules. |
|
||||
|
||||
## Common rationalizations (excuse → reality)
|
||||
|
||||
| Excuse | Reality |
|
||||
|---|---|
|
||||
| "Let me just grep -r to be safe" | Use `rg`; `grep -r` walks every node_modules (Rule G). |
|
||||
| "I'll check CLAUDE.md for conventions" | File channel is closed; read the mappa `AGENTS` entity (Rule 1). |
|
||||
| "Fixed and typecheck passed — done" | Infra changes need live-verify after reload, not headless (Rule L). |
|
||||
| "I'll jot this in my project memory" | Durable knowledge goes to a mappa wiki, never `memory/` (Rule D). |
|
||||
| "I'll write the spec to a repo file" | Spec goes to a mappa wiki concept; run `mappa-knowledge` first (Rule K). |
|
||||
| "The method is baked into this repo" | Method flavor is per-project, chosen by `mappa-bootstrap`. |
|
||||
|
||||
## Red flags (all = STOP and re-orient)
|
||||
|
||||
- You are searching with `grep -r` / `find` over a tree that can contain
|
||||
node_modules/dist/build.
|
||||
- You are reading `.wiki/CLAUDE.md` / `.tasks/` as the project canon on a
|
||||
mappa-based setup.
|
||||
- You are about to write durable knowledge to `memory/` or a local file.
|
||||
- You are about to write a spec to a repo file rather than a mappa wiki concept.
|
||||
- You changed an infra/MCP component and only "verified headless".
|
||||
- You are doing wiki work without running `mappa-knowledge` first.
|
||||
- You assume this project must use the vitya methodology — let `mappa-bootstrap`
|
||||
make that selection.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Does NOT select or swap the methodology flavor (→ `mappa-bootstrap`).
|
||||
- Does NOT write a project's AGENTS.md content (→ `project-bootstrap`).
|
||||
- Does NOT run the brainstorm/promotion method (→ `mappa-vitya-brainstorming`).
|
||||
- Does NOT install skills (→ `mappa-bootstrap` / `update-skills`).
|
||||
|
||||
## Cross-agent applicability
|
||||
|
||||
Behavior discipline with a mappa-media dependency. The mappa tool names are
|
||||
concrete (this zone runs on mappa); the RULES (read the durable canonical
|
||||
contract, master-only, semver, push-gate, rg-only search, live-verify, durable
|
||||
knowledge to the wiki) transfer to any mappa-based zone. On a non-mappa setup,
|
||||
substitute the corresponding knowledge channels.
|
||||
|
||||
`mappa-knowledge` is a mandatory precursor before any wiki work (Rule K): it
|
||||
loads the project's AGENTS entity and the read/ingest contract.
|
||||
@@ -102,9 +102,9 @@ target with `CLAUDE_SKILLS_DIR=/path bash scripts/install.sh …`.
|
||||
|
||||
- [`using-wiki`](../using-wiki/) — runtime policy for the mappa wiki (v2).
|
||||
- [`using-tasks`](../using-tasks/) — runtime policy for the mappa task board (v2).
|
||||
- [`mappa-vitya-project-discipline`](../mappa-vitya-project-discipline/)
|
||||
— vitya-flavored cross-project discipline (activated per-project by
|
||||
`mappa-bootstrap`, which selects the methodology flavor).
|
||||
- vitya-flavored cross-project discipline (activated per-project by
|
||||
`mappa-bootstrap`, which selects the methodology flavor) — moved to
|
||||
`victor/mappa-vitya-skills` (mappa-vitya-project-discipline).
|
||||
- [`setup-interns`](../setup-interns/), [`using-interns`](../using-interns/) —
|
||||
pair behind the `delegate to interns when allowed` trigger; cheap-LLM
|
||||
delegation under a per-session permission grant.
|
||||
|
||||
@@ -426,7 +426,7 @@ which lets Claude offload predictable bulk I/O and summarization tasks
|
||||
local `interns` MCP server (`mcp__interns__bulk_text_read`,
|
||||
`mcp__interns__transcript_distill`, etc.) — saves Anthropic quota at ~125× the
|
||||
per-call cost reduction on bulk reads. Per-session permission grant mirrors the
|
||||
`mappa-vitya-project-discipline` Rule 4: ask-mode default, conversational grant / revoke,
|
||||
`mappa-vitya-project-discipline` Rule 4 (skill moved to `victor/mappa-vitya-skills`): ask-mode default, conversational grant / revoke,
|
||||
always-ask paths for `.env` / secrets / keys / SSH credentials even with an
|
||||
active grant, session-end reset. The skill is a no-op until the `interns` MCP
|
||||
server is registered — install via `setup-interns` on a fresh machine if
|
||||
|
||||
Reference in New Issue
Block a user