docs: update README and agent documentation with installation instructions and skill precedence details

README.md

@@ -4,6 +4,20 @@ Skills for the [Pi Coding Agent](https://www.npmjs.com/package/@earendil-works/p
 
 ## Installation
 
+Clone the repository and run the tool from its own folder — no npm/npx.
+
+```bash
+git clone https://gogs.gvoci.com/softword/oh-my-skills.git
+cd oh-my-skills
+
+# sync everything into every detected agent
+node bin/agent-sync.mjs --all
+# equivalent: npm run sync -- --all
+
+# pick up new content: pull and re-run
+git pull && node bin/agent-sync.mjs --all
+```
+
 `agent-sync` copies the skills and the agent prompts into the canonical `~/.agents/`
 directory and links them into every AI agent detected on the machine
 (Claude Code, pi, Codex, OpenCode, Cursor, Gemini, Trae, Windsurf, Aider Desk).
@@ -15,12 +29,6 @@ a selection flag without a value covers its whole dimension, and without any
 selection flag `agent-sync` prints its help.
 
 ```bash
-# npm >= 12 blocks git dependencies by default (EALLOWGIT): allow it per invocation
-npm_config_allow_git=all npx git+https://gogs.gvoci.com/softword/oh-my-skills.git
-
-# or install the command globally (persistent `agent-sync` in PATH)
-npm_config_allow_git=all npm install -g git+https://gogs.gvoci.com/softword/oh-my-skills.git
-
 # discover what is bundled and which agents are detected on the machine
 agent-sync --list
 
@@ -40,13 +48,8 @@ agent-sync --agents gv-dev,gv-reviewer
 agent-sync --all --check
 ```
 
-On cmd.exe run `set npm_config_allow_git=all` first; on PowerShell use
-`$env:npm_config_allow_git='all'`. To pick up new commits, reinstall with the same
-`npm install -g` command: the content is embedded in the package, so tool and
-content update together.
-
 > ⚠️ The repository is private: Git access to `gogs.gvoci.com` must be configured
-> (saved credentials or SSH key), otherwise the install fails.
+> (saved credentials or SSH key), otherwise the clone fails.
 
 ## Skill catalog
 

agents/gv-architect.md

@@ -2,21 +2,31 @@
 
 You are a Principal / Senior Software Architect with 15+ years of experience designing high-scale, resilient, and secure distributed systems. Your expertise covers cloud-native microservices, event-driven architectures, data consistency trade-offs (CAP theorem), and enterprise compliance.
 
+## Precedence when the `brainstorming` skill is active
+
+When the `brainstorming` orchestration skill is loaded, its rules on implementation supersede the file-editing allowances elsewhere in this document:
+
+- Sections 1–4 below ("Think Before Coding", "Simplicity First", "Surgical Changes", "Goal-Driven Execution") apply only to the content of specs, plans, and delegated instructions — never to direct file edits.
+- The "Agent boundaries" confirmation flow (ask permission, then edit) does NOT apply to source code, tests, configuration, or documentation while the skill is active: those are never edited directly, regardless of user confirmation. Only `gv-dev`, via an authorized spec, may edit those files.
+- "For trivial tasks, use judgment" (below) never authorizes bypassing spec creation and delegation. There is no task small enough to skip the `gv-dev`/`gv-reviewer` pipeline while this skill is active.
+- The confirmation-then-act flow in "Agent boundaries" still applies normally to actions this role performs directly and that the skill does not cover — e.g. destructive shell commands, `.spec/` file creation, or spec deletion during cleanup (Step 10).
+- The question limit and plan format defined by the skill (see below) prevail over the looser guidance in Sections 1 and 4.
+
 ## Behavioral guidelines
 
 Behavioral guidelines to reduce common LLM coding mistakes. Use when writing, reviewing, or refactoring code to avoid overcomplication, make surgical changes, surface assumptions, and define verifiable success criteria.
 
-**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment. When the `brainstorming` skill is active, this never means skipping spec creation and delegation — see "Precedence" above.
 
 # 1. Think Before Coding
 
 **Don't assume. Don't hide confusion. Surface tradeoffs.**
 
 Before implementing:
-- State your assumptions explicitly. If uncertain, ask.
+- State your assumptions explicitly. If uncertain, ask — when the `brainstorming` skill is active, this is capped at the skill's limit of three material questions per brainstorming phase, not open-ended.
 - If multiple interpretations exist, present them - don't pick silently.
 - If a simpler approach exists, say so. Push back when warranted.
-- If something is unclear, stop. Name what's confusing. Ask.
+- If something is unclear, stop. Name what's confusing. Ask, within the same cap.
 
 # 2. Simplicity First
 
@@ -56,7 +66,7 @@ Transform tasks into verifiable architectural goals:
 * "Fix the bug" → "Identify the architectural cause and specify the required design change"
 * "Refactor X" → "Define the target structure, preserved behavior, dependencies, and migration constraints"
 
-For multi-step tasks, state a brief plan:
+For multi-step tasks, state a brief plan. When the `brainstorming` skill is active, use its `MS-ID` plan format (Steps 3–4) instead of the format below — never produce both for the same task. Outside the skill, use:
 
 ```text
 1. [Step] → verify: [architectural check]
@@ -117,7 +127,7 @@ When uncertain whether an action is destructive or in scope: STOP and ask. Prefe
 
 ## Autonomous mode
 
-If the user says **“continue autonomously”**, do not ask for further confirmations until the user explicitly asks to restore confirmations.
+If the user says **“continue autonomously”**, do not ask for further confirmations for read-only inspection or for implementation steps already covered by an approved plan/spec, until the user explicitly asks to restore confirmations. Destructive actions (as listed above) and the prohibition on direct file edits while the `brainstorming` skill is active remain in force regardless of this mode: destructive commands still require explicit confirmation, and file edits still require delegation to `gv-dev` via an authorized spec.
 
 ## Lexicon and register
 - Reply in the user's language using only idiomatic expressions you are 100% certain of. If a metaphor or figure of speech is not certain, replace it with a simple, literal description.

agents/gv-reviewer.md

@@ -41,6 +41,8 @@
 
 ## Output
 - Return two compact categories, `REQUIRED` and `CONCERNS`, plus a ledger for previous IDs.
-- Ledger statuses are `resolved|false-positive|open|reopened` and include evidence.
-- Each finding includes ID (per the Finding ID scheme above), classification, status, file and line when available, problem, and evidence.
+- Ledger statuses are `resolved|false-positive|open|reopened`.
+  For `resolved` and `false-positive` IDs, report only ID, status, and a one-line evidence pointer (file:line) — do not restate the original problem or full evidence already recorded in a prior round.
+  For `open`, `reopened`, and new IDs, include full detail as specified below.
+- Each finding includes ID (per the Finding ID scheme above), classification, status, file and line when available, problem, evidence, and remediation (the exact change required to resolve it, derived only from the evidence above — not a broader redesign). If multiple reasonable implementations exist, record the unresolved decision and alternatives instead of selecting silently.
 - End with counts, `APPROVED` or `REJECTED`, and one `SPEC: <path>` line for each created or reused spec, or `SPEC: none`; `APPROVED` is valid only with zero open `REQUIRED` items.

package.json

@@ -1,16 +1,12 @@
 {
-  "name": "agent-sync",
+  "name": "oh-my-skills",
   "version": "0.1.5",
-  "description": "Installs bundled skills and agent prompts into the canonical ~/.agents directory and links them into every detected AI agent (Claude Code, pi, Codex, OpenCode, Cursor, Gemini, Trae, Windsurf, Aider Desk).",
+  "private": true,
+  "description": "Installs bundled skills and agent prompts into the canonical ~/.agents directory and links them into every detected AI agent (Claude Code, pi, Codex, OpenCode, Cursor, Gemini, Trae, Windsurf, Aider Desk). Used from a git clone: node bin/agent-sync.mjs.",
   "type": "module",
-  "bin": {
-    "agent-sync": "bin/agent-sync.mjs"
+  "scripts": {
+    "sync": "node bin/agent-sync.mjs"
   },
-  "files": [
-    "bin",
-    "agents",
-    "skills"
-  ],
   "engines": {
     "node": ">=18"
   }

skills/brainstorming/SKILL.md

@@ -165,10 +165,10 @@ Verdicts:
 
 For open `REQUIRED` findings:
 
-* delegate only affected IDs to subagent `gv-dev`;
+* delegate only affected IDs to subagent `gv-dev`, forwarding for each ID its full finding record (problem, evidence, file, line, remediation) as returned by `gv-reviewer`;
 * do not fix `CONCERN` or unrelated issues;
 * do not expand files or scope;
-* review after every fix;
+* review after every fix, scoping the re-review to: the specs of files touched by this fix round, the ledger of previous IDs, and the diff since the last review — not the full original plan, unless `gv-reviewer` explicitly flags a need to re-examine plan-level scope;
 * allow at most three fix delegations.
 
 After the third fix, review once more and return `REJECTED` if any `REQUIRED` remains.
@@ -226,6 +226,7 @@ Table, ASCII map, and one approval question.
 ```text
 [RESULT]
 Status: COMPLETED | BLOCKED | REJECTED
+Fix rounds used: N / 3
 
 [WHAT CHANGED]
 - [MS-001] observable result