claude-dev-env 8.1.0 → 8.3.0

package/.agents/agents/poteto-agent.md

@@ -0,0 +1,6 @@
+---
+name: poteto-agent
+description: Use the installed pstack poteto-mode agent for delegated work.
+---
+
+Read the installed pstack `poteto-mode/SKILL.md` in full before any work. Follow its instructions for this task.

package/.agents/agents/test_agent_frontmatter.py

@@ -81,7 +81,7 @@ import yaml
 ACCEPTED_FRONTMATTER_KEYS = frozenset({"name", "description", "tools", "color"})
 CODE_QUALITY_AGENT_FILENAME = "code-quality-agent.md"
 CODE_QUALITY_READ_ONLY_TOOLS = ("Read", "Grep", "Glob")
-INSTRUCTION_ALIAS_FILENAMES = frozenset({"AGENTS.md", "CLAUDE.md"})
+INSTRUCTION_ALIAS_FILENAMES = frozenset({"AGENTS.md", "CLAUDE.md", "ARCHIVE-MANIFEST.md"})
 FRONTMATTER_FENCE_LINE = "---"
 MATERIALIZER_MODULE_NAME = "codex_compat_materializer"
 MATERIALIZER_MODULE_PATH = (
@@ -124,7 +124,7 @@ def _agent_definition_candidate_paths() -> tuple[Path, ...]:
     Returns:
         Every agent-definition `*.md` path in this directory, sorted.
     """
-    agents_directory = Path(__file__).parent
+    agents_directory = Path(__file__).parent.parent / "agents-archived"
     return tuple(
         each_markdown_file
         for each_markdown_file in sorted(agents_directory.glob("*.md"))
@@ -298,7 +298,7 @@ def test_agent_frontmatter_loads_as_a_yaml_mapping(
 )
 def named_agents_yaml_safe_load_as_mapping(agent_file_name: str) -> None:
     """P-107 regression: named agents remain real YAML mappings under safe_load."""
-    agent_definition_path = Path(__file__).parent / agent_file_name
+    agent_definition_path = Path(__file__).parent.parent / "agents-archived" / agent_file_name
     assert agent_definition_path.is_file(), (
         f"{agent_file_name} missing from agents/ — P-107 surface gone"
     )
@@ -419,7 +419,7 @@ def test_agent_frontmatter_carries_no_model_key(
 
 
 def _clean_coder_body() -> str:
-    return (Path(__file__).parent / "clean-coder.md").read_text(encoding="utf-8")
+    return (Path(__file__).parent.parent / "agents-archived" / "clean-coder.md").read_text(encoding="utf-8")
 
 
 SOURCE_LINK_PATTERN = re.compile(
@@ -602,7 +602,7 @@ EXPECTED_SOURCE_LINK_PAIRS = {
 
 
 def _assert_source_link_contract(agent_file_name: str, agent_text: str) -> None:
-    agents_directory = Path(__file__).parent
+    agents_directory = Path(__file__).parent.parent / "agents-archived"
     repository_root = agents_directory.parents[3]
     actual_source_links = frozenset(SOURCE_LINK_PATTERN.findall(agent_text))
     expected_source_links = EXPECTED_SOURCE_LINK_PAIRS[agent_file_name]
@@ -624,7 +624,7 @@ def _assert_source_link_contract(agent_file_name: str, agent_text: str) -> None:
 
 
 def test_named_agents_document_installed_paths_and_source_fallbacks() -> None:
-    agents_directory = Path(__file__).parent
+    agents_directory = Path(__file__).parent.parent / "agents-archived"
     for each_agent_file_name in (
         "clean-coder.md",
         "code-quality-agent.md",
@@ -687,7 +687,7 @@ def test_source_link_contract_rejects_directory_fallback() -> None:
 
 
 def test_named_agents_resolve_active_managed_root_and_agents_home() -> None:
-    agents_directory = Path(__file__).parent
+    agents_directory = Path(__file__).parent.parent / "agents-archived"
     for each_agent_file_name in (
         "clean-coder.md",
         "code-quality-agent.md",
@@ -906,14 +906,14 @@ def test_clean_coder_policy_targets_exist_in_source_package() -> None:
 
 
 def test_code_quality_agent_allows_only_read_and_search_tools() -> None:
-    agent_definition_path = Path(__file__).parent / CODE_QUALITY_AGENT_FILENAME
+    agent_definition_path = Path(__file__).parent.parent / "agents-archived" / CODE_QUALITY_AGENT_FILENAME
     parsed_frontmatter = yaml.safe_load(_frontmatter_block(agent_definition_path))
 
     assert parsed_frontmatter["tools"] == list(CODE_QUALITY_READ_ONLY_TOOLS)
 
 
 def test_code_quality_agent_contract_forbids_mutating_commands() -> None:
-    agent_definition_path = Path(__file__).parent / CODE_QUALITY_AGENT_FILENAME
+    agent_definition_path = Path(__file__).parent.parent / "agents-archived" / CODE_QUALITY_AGENT_FILENAME
     body = agent_definition_path.read_text(encoding="utf-8")
     assert "Use only `Read`, `Grep`, and `Glob`." in body
     assert "Author zero edits." in body

package/.agents/agents/test_pr_description_writer_style.py

@@ -4,7 +4,7 @@ from pathlib import Path
 
 
 AGENT_DIRECTORY = Path(__file__).parent
-AGENT_PATH = AGENT_DIRECTORY / "pr-description-writer.md"
+AGENT_PATH = AGENT_DIRECTORY.parent / "agents-archived" / "pr-description-writer.md"
 VOICE_REFERENCE_PATH = AGENT_DIRECTORY / "reference" / "pr-description-illustrative-voice.md"
 VERIFICATION_REFERENCE_PATH = AGENT_DIRECTORY / "reference" / "pr-description-verification.md"
 

package/.agents/agents-archived/ARCHIVE-MANIFEST.md

@@ -0,0 +1,15 @@
+# Archived agent definitions
+
+These definitions are archived outside the package's active agent tree. Restore
+one with the `git mv` command in its row, then restore the named caller and test edits.
+
+| File | Reason | Restore |
+|---|---|---|
+| `clean-coder.md` | Personal coding workflow now routes through `pstack:poteto-agent` with task instructions in each call. | `git mv packages/claude-dev-env/.agents/agents-archived/clean-coder.md packages/claude-dev-env/.agents/agents/` and restore active caller references plus agent contract tests. |
+| `code-quality-agent.md` | Personal review workflow now routes through `pstack:poteto-agent` with review instructions in each call. | `git mv packages/claude-dev-env/.agents/agents-archived/code-quality-agent.md packages/claude-dev-env/.agents/agents/` and restore active caller references plus agent contract tests. |
+| `git-commit-crafter.md` | Personal commit drafting workflow is archived with the other package-owned agents. | `git mv packages/claude-dev-env/.agents/agents-archived/git-commit-crafter.md packages/claude-dev-env/.agents/agents/` and restore the model policy entry. |
+| `issue-tracker.md` | Personal issue handling workflow now routes through `pstack:poteto-agent` loading the issue-tracker skill. | `git mv packages/claude-dev-env/.agents/agents-archived/issue-tracker.md packages/claude-dev-env/.agents/agents/` and restore active issue routing plus installer and contract tests. |
+| `plan-packet-validator.md` | Personal plan validation workflow is archived with the other package-owned agents. | `git mv packages/claude-dev-env/.agents/agents-archived/plan-packet-validator.md packages/claude-dev-env/.agents/agents/` and restore the model policy entry. |
+| `pr-description-writer.md` | Personal PR drafting workflow now routes through `pstack:poteto-agent` with diff-specific writing instructions. | `git mv packages/claude-dev-env/.agents/agents-archived/pr-description-writer.md packages/claude-dev-env/.agents/agents/` and restore active PR routing plus installer and contract tests. |
+| `session-advisor.md` | Personal advisor workflow now routes through `pstack:poteto-agent` with the advisor response contract in the prompt. | `git mv packages/claude-dev-env/.agents/agents-archived/session-advisor.md packages/claude-dev-env/.agents/agents/` and restore advisor routing, resolver, and contract tests. |
+| `skill-writer-agent.md` | Personal skill authoring workflow is archived with the other package-owned agents. | `git mv packages/claude-dev-env/.agents/agents-archived/skill-writer-agent.md packages/claude-dev-env/.agents/agents/` and restore the model policy entry. |

package/.agents/{agents → agents-archived}/clean-coder.md

@@ -79,7 +79,7 @@ Load only the group that matches the task. Keep session policy details in these
 
 Material implementation questions must return to the caller for `AskUserQuestion` handling; do not ask in plain text or guess.
 
-Type-ignore rule (AGENTS Types): avoid `# type: ignore`; remove it and use a typed boundary or real type.
+Type-ignore rule (AGENTS Types): avoid `# type: ignore`; remove it and use a typed boundary or type.
 
 Constants (AGENTS Magic values): use named constants from the target layout. Search its constants module first. Do not force a generic `config/` layout. Example:
 
@@ -101,7 +101,7 @@ def fetch_with_retries(fetch_text: Callable[[str], str], url: str) -> str:
 - **No secrets in context.** Never open `.env` / `.env.*` / credential files. The sensitive-file protector blocks editing them.
 - **No lock-file hand edits.** Do not edit lock files by hand; regenerate with the package manager.
 - **No unasked scratch files.** Follow the target repo's policy for scratch, planning, and image files. Do not create temporary scratch files or working docs. Keep valid plan packets under `docs/plans/` as uncommitted working files when the task calls for them. Store required images in the durable artifacts release, not the repository tree.
-- **Pre-check before Write.** Run `python <managed-root>/hooks/blocking/code_rules_enforcer.py --check <candidate> --as <real destination>` (install path; monorepo: `packages/claude-dev-env/hooks/blocking/code_rules_enforcer.py`) until clean, then Write/Edit once. Use the real `--as` path; a wrong path can hide violations. This is the mechanical CODE_RULES check; it does not run tests, ruff, mypy, or the full quality gate.
+- **Pre-check before Write.** Run `python <managed-root>/hooks/blocking/code_rules_enforcer.py --check <candidate> --as <destination>` (install path; monorepo: `packages/claude-dev-env/hooks/blocking/code_rules_enforcer.py`) until clean, then Write/Edit once. Use the `--as` path; a wrong path can hide violations. This is the mechanical CODE_RULES check; it does not run tests, ruff, mypy, or the full quality gate.
 - **Candidate check vs full gate.** The pre-check tests CODE_RULES only. The full project gate runs over the complete diff and all required checks. `code_rules_enforcer.py --check` checks one candidate file before a write; a clean candidate enforcer check is not the full gate.
 - **Windows shell.** Author multi-line scripts with the Write or PowerShell tool; avoid bash heredocs that mangle paths.
 - **`gh` bodies.** Always `--body-file`; never use `--body` or `-b` with markdown.
@@ -113,7 +113,7 @@ def fetch_with_retries(fetch_text: Callable[[str], str], url: str) -> str:
 
 Every behavior change follows Red-Green-Refactor:
 
-1. **RED** — write a failing test first against the real production path, with real data; run it red and keep the failure as evidence.
+1. **RED** — write a failing test first against the production path, with production data; run it red and keep the failure as evidence.
 2. **GREEN** — write the minimum production change, then run the focused test.
 3. **REFACTOR** — change structure only after GREEN, then run the focused test again.
 
@@ -121,7 +121,7 @@ Do not write production behavior before RED, skip the red run, or call a green t
 
 ## Hook-specific workflow
 
-For a hook change, use the target package's active managed root for installed files, not the current working directory. The default is `~/.claude`; `--target` or `CLAUDE_CONFIG_DIR` selects another managed root. Read `<managed-root>/hooks/AGENTS.md` (default: `~/.claude/hooks/AGENTS.md`; source fallback: `packages/claude-dev-env/hooks/AGENTS.md`), each closer `AGENTS.md` and `CLAUDE.md`, and the registered hook entry before editing. Trace the lifecycle event, stdin JSON, output contract, exit code, and registration. Reuse the target hook area's constants package. Run `<managed-root>/scripts/check.ps1` (default: `~/.claude/scripts/check.ps1`; source fallback: `packages/claude-dev-env/scripts/check.ps1`) and drive the real production entry point with event payloads. The RED test covers each allow and deny outcome. Run every applicable test file and suite for the hook, then the full quality gates required by the affected package.
+For a hook change, use the target package's active managed root for installed files, not the current working directory. The default is `~/.claude`; `--target` or `CLAUDE_CONFIG_DIR` selects another managed root. Read `<managed-root>/hooks/AGENTS.md` (default: `~/.claude/hooks/AGENTS.md`; source fallback: `packages/claude-dev-env/hooks/AGENTS.md`), each closer `AGENTS.md` and `CLAUDE.md`, and the registered hook entry before editing. Trace the lifecycle event, stdin JSON, output contract, exit code, and registration. Reuse the target hook area's constants package. Run `<managed-root>/scripts/check.ps1` (default: `~/.claude/scripts/check.ps1`; source fallback: `packages/claude-dev-env/scripts/check.ps1`) and drive the production entry point with event payloads. The RED test covers each allow and deny outcome. Run every applicable test file and suite for the hook, then the full quality gates required by the affected package.
 
 ## Session advisor
 

package/.agents/{agents → agents-archived}/code-quality-agent.md

@@ -127,7 +127,7 @@ evidence, report an evidence gap or open question.
 
 `id` uses the form `loop<N>-<K>` when the orchestrator supplies a loop prefix and `find<K>` for standalone audit calls. Honor the prefix supplied in the prompt.
 
-**The `failure_mode` field is the audit-to-fix handoff.** State the failing line, the desired post-fix property, and a one-line validation the fix agent can run to confirm correctness. The fix agent reads `failure_mode` without re-running your audit — make it self-sufficient.
+**The `failure_mode` field is the audit-to-fix handoff.** State the failing line, the desired post-fix property, and a one-line validation the fix agent can run to confirm correctness. The fix agent reads `failure_mode` without re-running your audit — make it stand on its own.
 
 Each audit→fix→audit cycle in the calling skill adds wall-clock latency. A vague `failure_mode` forces another cycle to clarify; a precise `failure_mode` lets the fix land in one cycle. Word choice in this field directly controls how many cycles the loop takes.
 
@@ -165,9 +165,9 @@ not a Shape B entry.
 
 ## Collection before filtering
 
-Report every real finding at its true severity. Collection retains P0, P1, and
+Report every finding at the severity it warrants. Collection retains P0, P1, and
 P2 findings with file, line, evidence (`excerpt` / `failure_mode`), and
-category. Do not drop lower-severity real findings during collection so a later
+category. Do not drop lower-severity findings during collection so a later
 consumer can filter. Severity or action filtering is a separate stage after the
 collection record is complete.
 
@@ -189,7 +189,7 @@ The second pass produces either:
 - new Shape A findings citing file:line references absent from the first pass, or
 - explicit Shape B `adversarial_probes` entries for each re-examined category.
 
-A second pass that returns "first pass was complete, confidence high" is inadequate per the audit contract — confidence is replaced by either new findings or new adversarial evidence per category.
+A second pass that returns "first pass was complete, confidence high" is inadequate per the audit contract. Confidence must yield new findings or new adversarial evidence per category.
 
 ## Merging Primary and Adversarial Findings
 
@@ -197,7 +197,7 @@ When the primary and adversarial passes flag the same file:line:
 
 - Merge into a single Shape A finding using max-wins severity (P0 > P1 > P2).
 - Concatenate the `failure_mode` strings (separator: " // adversarial: ") so both pass narratives survive.
-- For Shape B entries on the same category, keep every distinct `adversarial_probe` from both passes — collapsing them would drop information that was actually found.
+- For Shape B entries on the same category, keep every distinct `adversarial_probe` from both passes — collapsing them would drop information that was found.
 
 The merge runs at the end of the adversarial pass, before constructing the output. The output preamble's `Total: N` counts merged findings, not pre-merge total.
 

package/.agents/{agents → agents-archived}/plan-packet-validator.md

@@ -20,7 +20,7 @@ You validate plan packets. You are not the planner and you do not repair docs.
 1. Read `README.md`, `packet.json`, `context/source-map.md`, `implementation/steps.md`, `implementation/tdd-plan.md`, `spec/acceptance.md`, and `handoff/build-prompt.md`.
 2. Read or search the source files named in `source-map.md` and `packet.json`.
 3. Verify referenced paths exist unless the packet clearly labels them as new files.
-4. Verify source facts match actual files.
+4. Verify source facts match the files.
 5. Verify the implementation steps are enough for a blind build agent.
 6. Verify the TDD sequence starts with failing tests and names the behavior those tests prove.
 7. Verify scope matches the user request and non-goals.
@@ -30,4 +30,4 @@ You validate plan packets. You are not the planner and you do not repair docs.
 
 ## Output
 
-Return the requested structured schema. Set `allPassed` to true only when every check is clean. Each finding must name the packet file, the check, and the exact source-grounded problem.
+Return the requested structured schema. Set `allPassed` to `true` only when every check is clean. Each finding must name the packet file, the check, and the exact source-grounded problem.

package/.agents/{agents → agents-archived}/session-advisor.md

@@ -5,7 +5,7 @@ tools: SendMessage
 color: cyan
 ---
 
-You are a standing reviewer a Claude Code session consults across the life of a task — not only when it is stuck, but before it commits to a plan, once it believes the work is finished, before any commit is executed, and when it is weighing whether to change course. Your only tool is SendMessage, used to reply to the sender of each consult by name. Everything else you know arrives in the consultation message: what changed since the last consult, the live decision or question, and any file paths or excerpts the session chose to include.
+You are a standing reviewer a Claude Code session consults across the life of a task. The session consults you before it commits to a plan, once it believes the work is finished, before any commit is executed, and when it weighs whether to change course. Your only tool is SendMessage, which replies to the sender of each consult by name. Everything else you know arrives in the consultation message: what changed since the last consult, the live decision or question, and any file paths or excerpts the session chose to include.
 
 Many different consumers may reach you over one shared transcript — a coordinating session and the executor subagents it spawns, not just the single session that spawned you. Three things follow from that:
 
@@ -16,7 +16,7 @@ Many different consumers may reach you over one shared transcript — a coordina
 Reply with exactly one of four signals, named on the first line:
 
 - **ENDORSE** — the plan, or the finished work, holds up, with nothing worth flagging. A clean yes.
-- **CORRECTION** — something needs attention before the plan or the finished work is genuinely done: a wrong assumption or step, or a risk worth naming and closing. Name the specific problem(s) and the precise fix(es) or mitigation(s). A risk you would otherwise have mentioned in passing belongs here, not folded into an ENDORSE.
+- **CORRECTION** — something needs attention before the plan or the finished work is done: a wrong assumption or step, or a risk worth naming and closing. Name the specific problem(s) and the precise fix(es) or mitigation(s). A risk you would otherwise have mentioned in passing belongs here, not folded into an ENDORSE.
 - **PLAN** — the current approach needs to change. Give concrete ordered steps the session can run with its own tools, naming files, commands, and decision points.
 - **STOP** — no path satisfies the task as assigned (contradictory constraints, missing access, a rule that forbids every way through). Say why, and report your reasoning with cited proof and examples.
 

package/.agents/skills/_shared/end-of-run-gotcha-recommendations.md

@@ -29,7 +29,7 @@ Keep only items that **bit this run**:
 
 1. Show findings in chat; categorize as P0-P3.
 2. Then `AskUserQuestion`.
-3. On confirm only, file via `issue-tracker`.
+3. On confirm only, ask `pstack:poteto-agent` to load `issue-tracker` and file the issue.
 
 ### Cold-reader frame
 
@@ -126,7 +126,7 @@ Only after the chat block.
 
 Detail and ASCII stay in chat.
 
-**On confirm:** file via `issue-tracker`.
+**On confirm:** ask `pstack:poteto-agent` to load `issue-tracker` and file the issue.
 
 Cold-reader issue body.
 

package/.agents/skills/cert-classification-rule/SKILL.md

@@ -135,7 +135,7 @@ truthful note, because it becomes the pasted sentence for those classes.
 
 Do **not** fabricate a "Samsung confirmed" claim. State only what is true. The shipped Gallery
 note is true because Samsung Support did confirm that issue; a new pattern for a different
-issue must not borrow that wording unless the confirmation actually happened.
+issue must not borrow that wording unless the confirmation happened.
 
 ## How to add the paired production-path test
 
@@ -143,7 +143,7 @@ Every new unfixable pattern gets a paired test in
 `shared_utils/samsung_utils/tests/test_cert_failure_classifier.py` that drives the production
 path:
 
-1. Load the real patterns with `load_unfixable_patterns()` (no path argument, so it reads the
+1. Load the patterns with `load_unfixable_patterns()` (no path argument, so it reads the
    shipped config).
 2. Build the report HTML with the live must-fix title text, run it through
    `extract_issue_titles`, then `classify_failure`, and assert the result is `unfixable`.
@@ -153,7 +153,7 @@ path:
 
 Use the exact title strings Samsung's report produces. The existing
 `TestClassifyFailure::test_gallery_regex_matches_all_known_variants` shows the shape: a list of
-real title variants, each asserted as `unfixable` through `classify_failure`.
+title variants, each asserted as `unfixable` through `classify_failure`.
 
 Run the tests from the `shared_utils` directory (its pytest config is anchored there):
 

package/.agents/skills/e-code-review/SKILL.md

@@ -24,7 +24,7 @@ Proposal mode selects the review level and records finding outcomes. The downstr
 ## Gotchas
 
 - **`low` stays single-pass.** No subagents, no full-file reads: one read pass per target item, one findings pass.
-- **Collection reports every real finding.** Keep every CONFIRMED or PLAUSIBLE finding at its assigned severity (`blocker`, `high`, `medium`, `low`, `nit`). Do not drop low or nit findings during collection. Severity or action filtering is a separate consumer stage after the collection record is complete (`scripts/finding_pipeline.py`).
+- **Collection reports every finding.** Keep every CONFIRMED or PLAUSIBLE finding at its assigned severity (`blocker`, `high`, `medium`, `low`, `nit`). Do not drop low or nit findings during collection. Severity or action filtering is a separate consumer stage after the collection record is complete (`scripts/finding_pipeline.py`).
 - **`medium` favors precision, `xhigh` favors recall.** At `medium` (8 angles) assign severity carefully so a later filter can pick maintainer-action findings. At `xhigh` (10 angles plus a gap sweep) a single non-REFUTED vote carries the finding; do not drop on uncertainty.
 - **Every retained finding carries `severity` and `verdict`.** Severity is one of `blocker`, `high`, `medium`, `low`, `nit`. Verdict is `CONFIRMED` or `PLAUSIBLE`. Drop REFUTED candidates only; never emit an unclassified retained finding.
 - **`--fix` applies findings once.** Load `reference/fix.md` and follow it. That file owns the fix agent, the code-rules gate, skip logging, and outcome reporting. Commits are lead-owned; fix agents never commit or push.
@@ -74,7 +74,7 @@ Detail: `reference/effort-evaluation.md`.
 | `reference/preflight-proposal.md` | Isolated local review, immutable SHAs, proposal evidence, and mutation boundary |
 | `reference/effort-evaluation.md` | Effort evaluation fixtures, evidence, and skill defaults |
 | `reference/runner-selection.md` | Runner selection map |
-| `scripts/finding_pipeline.py` | Collect every real finding; filter severity only later |
+| `scripts/finding_pipeline.py` | Collect every finding; filter severity only later |
 | `scripts/test_finding_pipeline.py` | Collection and filter-stage behavioral tests |
 | `scripts/e_code_review_scripts_constants/finding_pipeline_constants.py` | Named constants for the collect-then-filter pipeline |
 | `scripts/effort_evaluation.py` | Effort rows, recommendation, skill default resolver |

package/.agents/skills/e-code-review/reference/fix.md

@@ -66,7 +66,7 @@ After fixes land, report the same findings list again through the structured
 findings-report call, the call that renders this review's results as a typed
 list in the host UI, with each finding now carrying an `outcome`:
 `fixed`, `no_change_needed` (the finding was wrong or already handled), or
-`skipped` (real but not applied). Do not repeat the findings as text in the
+`skipped` (the finding stands but no fix was applied). Do not repeat the findings as text in the
 response body; the structured call is the record the host UI reads, and the
 batched skip list from above goes in the prose that follows it.
 

package/.agents/skills/e-code-review/reference/loop.md

@@ -183,7 +183,7 @@ round's progress report. Then take the one case that matches the round's
 findings.
 
 - Any bug-severity finding: validate each bug with an advisor before touching
-  code. Confirm it's real and confirm the intended fix, then fix every
+  code. Confirm the bug exists and confirm the intended fix, then fix every
   validated bug and every nit on the review target. A refuted bug removes only
   itself from the round's work; the nits are fixed either way.
 - Nits only, with at least one nit present: fix all of them on the review

package/.agents/skills/e-code-review/reference/medium.md

@@ -2,7 +2,7 @@
 
 You are reviewing for **precision** at medium effort: assign severity carefully
 so a later consumer can select maintainer-action findings. **Collection
-reports every real finding** (including `low` and `nit`); do not drop by
+reports every finding** (including `low` and `nit`); do not drop by
 severity during collection. Severity filtering is a separate consumer stage
 after the collection record is complete.
 
@@ -44,7 +44,7 @@ wrong-variable copy-paste, error swallowed in catch, unescaped regex metachars.
 For every line the diff DELETES or replaces, name the invariant or behavior it
 enforced, then search the new code for where that invariant is re-established.
 If you can't find it, that's a candidate: a removed guard, a dropped error
-path, a narrowed validation, a deleted test that was covering a real case.
+path, a narrowed validation, a deleted test that was covering a case.
 
 ### Angle C — cross-file tracer
 
@@ -115,7 +115,7 @@ file(s), and the candidate, and have it return exactly one of:
 
 - **CONFIRMED** — can name the inputs/state that trigger it and the wrong
   output or crash. Quote the line.
-- **PLAUSIBLE** — mechanism is real, trigger is uncertain (timing, env,
+- **PLAUSIBLE** — mechanism is present in the code, trigger is uncertain (timing, env,
   config). State what would confirm it.
 - **REFUTED** — factually wrong (code doesn't say that) or guarded elsewhere.
   Quote the line that proves it.
@@ -126,7 +126,7 @@ Keep candidates where the vote is CONFIRMED or PLAUSIBLE.
 
 **Collection stage first.** Keep every CONFIRMED or PLAUSIBLE finding in the
 collection record, including `low` and `nit`. Drop only REFUTED candidates.
-Do not drop a real finding because its severity is low.
+Do not drop a finding because its severity is low.
 
 Report this review's results — `{level, findings}` — through the structured
 findings-report call: the mechanism that renders a review's results as a typed

package/.agents/skills/e-code-review/reference/xhigh.md

@@ -1,7 +1,7 @@
 `xhigh effort → 5+5 angles → 1-vote verify → sweep`
 
-You are reviewing for **recall** at extra-high effort: catch every real bug. At
-this level, catching real bugs matters more than avoiding false positives — a
+You are reviewing for **recall** at extra-high effort: catch every bug. At
+this level, catching bugs matters more than avoiding false positives — a
 missed bug ships. Err on the side of surfacing.
 
 ## Phase 0 — Gather the diff
@@ -42,7 +42,7 @@ wrong-variable copy-paste, error swallowed in catch, unescaped regex metachars.
 For every line the diff DELETES or replaces, name the invariant or behavior it
 enforced, then search the new code for where that invariant is re-established.
 If you can't find it, that's a candidate: a removed guard, a dropped error
-path, a narrowed validation, a deleted test that was covering a real case.
+path, a narrowed validation, a deleted test that was covering a case.
 
 ### Angle C — cross-file tracer
 
@@ -65,7 +65,7 @@ adapter): check that every method routes to the wrapped instance and not back
 through a registry/session/global — e.g. a caching provider holding a
 `delegate` field that resolves IDs via `session.get(...)` instead of
 `delegate.get(...)` will re-enter the cache or recurse. Also check that the
-wrapper forwards all the methods the callers actually use.
+wrapper forwards all the methods the callers use.
 
 ### Reuse
 
@@ -125,7 +125,7 @@ file(s), and the candidate, and have it return exactly one of:
 
 - **CONFIRMED** — can name the inputs/state that trigger it and the wrong
   output or crash. Quote the line.
-- **PLAUSIBLE** — mechanism is real, trigger is uncertain (timing, env,
+- **PLAUSIBLE** — mechanism is present in the code, trigger is uncertain (timing, env,
   config). State what would confirm it.
 - **REFUTED** — factually wrong (code doesn't say that) or guarded elsewhere.
   Quote the line that proves it.

package/.agents/skills/everything-search/SKILL.md

@@ -152,16 +152,16 @@ Run separate searches for each extension type:
 
 ### Junctions, Symlinks & Drive Mapping
 
-Everything indexes REAL paths only, not junctions or mapped drives.
+Everything indexes paths only, not junctions or mapped drives.
 
 | Drive | Type | Indexed? | Action |
 |-------|------|----------|--------|
-| Y:\ | Real NTFS | Yes | Use this path |
+| Y:\ | NTFS | Yes | Use this path |
 | Z:\ | Junction to Y: | No | Use Y:\ instead |
 
 **If search returns empty:**
 1. Check if the path is a junction/symlink
-2. Find the real path and search that instead
+2. Find the path the junction targets and search that instead
 3. Or use Glob tool as fallback (works on any path)
 
 **Common drive mappings:**

package/.agents/skills/grok-spawn/SKILL.md

@@ -16,7 +16,11 @@ the scripts and the brief templates; it holds no spawn logic of its own.
 - Workers never commit, push, or call `gh`. The calling session stages, verifies,
   commits, pushes, and posts to GitHub.
 - Grok has no `SendMessage` and no Claude Agent tool. Work that needs live
-  teammate chat or Claude-only tools stays in this session or a Claude agent.
+  teammate chat stays in this session. Each Grok worker uses `poteto-agent`.
+  The runner resolves the user pstack plugin through the selected Claude
+  profile's `plugins/installed_plugins.json` and includes its poteto skill content and
+  its resolved path in the prompt. Each task states its role, permitted edits,
+  acceptance checks, and report contract.
 - Each worker gets its own `--leader-socket`. Sharing one socket across processes
   races and fails.
 - Preflight is a soft gate: a fallthrough reason means skip the fleet and use
@@ -39,7 +43,7 @@ Good fits:
 **Do not use** when the work needs:
 
 - Live `SendMessage` coordination between agents
-- Claude-only tools (Agent tool, warm session-advisor, Claude MCP surfaces the
+- Claude-only tools (Agent tool, warm advisor, Claude MCP surfaces the
   grok CLI does not load the same way)
 
 For a single interactive Grok Build handoff paste, use `/grokify` instead.
@@ -125,7 +129,7 @@ Shape:
       "tool_profile": "readonly",
       "timeout_seconds": 600,
       "is_repo_only": true,
-      "agent_name": null
+      "agent_name": "poteto-agent"
     }
   ]
 }
@@ -133,7 +137,7 @@ Shape:
 
 | Field | Meaning |
 |---|---|
-| `role` | Preflight role whose agent files must be installed (default `bugteam`) |
+| `role` | Preflight role configuration to check (default `bugteam`) |
 | `should_ping` | When true, preflight runs the opt-in live ping |
 | `workers` | Non-empty list of worker objects |
 | `role_name` | Label on the summary report for this worker |
@@ -142,7 +146,7 @@ Shape:
 | `tool_profile` | `readonly` or `build` |
 | `timeout_seconds` | Per-worker timeout (default 600, ceiling 5400). A spec asking for more is refused |
 | `is_repo_only` | Readonly only: when true, also pass `--disable-web-search` |
-| `agent_name` | Optional `--agent` name, or `null` |
+| `agent_name` | Use `poteto-agent`; prompts carry the worker role. |
 
 Workers run with no turn cap. The timeout is the only bound on a worker's
 length, and a worker that hits it is killed with its whole process tree and
@@ -235,4 +239,3 @@ Sibling skill: `/grokify` for a single paste-ready interactive Grok Build handof
 ## Worker advisors
 
 Each grok worker binds a unique Opus-high dvisor_session_id through the lead-supplied dvisor.launcher in the batch spec (committed default is a placeholder). Reports require the same handle\'s ENDORSE (or bounded CORRECTION/PLAN then ENDORSE); STOP or malformed signals end as advisor_blocked.
-

package/.agents/skills/grok-spawn/reference/flag-profiles.md

@@ -109,15 +109,19 @@ The batch launcher applies this; you do not sleep in the skill.
 When `agent_name` is set, the runner passes `--agent <name>`. Grok loads the
 named agent charter from the **user-level** Claude config home (`~/.claude/`):
 
-- `agents/` — agent definition files (for example `code-quality-agent.md`,
-  `clean-coder.md`)
+- `agents/` contains `poteto-agent.md`.
 - `skills/`, `rules/`, `hooks/` — the rest of the installed Claude config the
   grok CLI reads for that run
 
-Preflight role `bugteam` checks that `code-quality-agent.md` and
-`clean-coder.md` exist under `~/.claude/agents/` and that the
-`claude-dev-env` install manifest is present. Install or reinstall
-`claude-dev-env` before a fleet that relies on those agents.
+Preflight checks the installed `poteto-agent.md`, the poteto skill,
+and the `claude-dev-env` install manifest. `CLAUDE_CONFIG_DIR` selects the
+configuration root when set. The runner includes the complete skill content
+and its resolved source path in each `poteto-agent` prompt. The task brief
+states the worker's duty and write permissions. The user pstack entry in
+`plugins/installed_plugins.json` selects the skill source. Companion paths stay
+relative to that source. Without a user pstack entry, the shared
+`skills/poteto-mode/SKILL.md` path is supported. Invalid metadata or an unreadable
+selected source fails the gate, even when a shared copy exists.
 
 Pass `agent_name: null` (or omit the field) when the worker should run without
 a named agent charter.
@@ -130,5 +134,5 @@ a named agent charter.
 |---|---|---|---|
 | Map call sites in-repo only | `readonly` | `true` | `null` or an audit agent |
 | Research that may need the web | `readonly` | `false` | `null` |
-| Closed edit + tests | `build` | ignored | often `clean-coder` |
-| Audit-style read under a charter | `readonly` | as needed | `code-quality-agent` |
+| Closed edit + tests | `build` | ignored | often `poteto-agent` |
+| Audit-style read under a charter | `readonly` | as needed | `poteto-agent` |

package/.agents/skills/issue-tracker/SKILL.md

@@ -15,9 +15,9 @@ argument-hint: "[issue action - file | update | close | refresh-epic | full hand
 
 **dedup -> do the work -> markers only -> numbers + URLs**
 
-Run every step the ask needs in one go (file, label, attach, refresh, and so on). The `issue-tracker` agent is the primary handler for one action per turn; this skill is the session path when the agent is unavailable or the ask spans several steps.
+Run every step the ask needs in one go (file, label, attach, refresh, and so on). `pstack:poteto-agent` is the primary handler for one action per turn when it loads this skill; this skill is the session path when the agent is unavailable or the ask spans several steps.
 
-Prefer the **same warm** `issue-tracker` agent for follow-ups on the same issue or a related issue on the same epic. Spawn a new agent only for an unrelated work-stream or when the warm agent is gone.
+Prefer the **same warm** `pstack:poteto-agent` for follow-ups on the same issue or a related issue on the same epic. Spawn a new agent only for an unrelated work-stream or when the warm agent is gone.
 
 ## Voice
 
@@ -79,7 +79,7 @@ GitHub closes the sub-issue when someone **merges** a pull request into the **de
 
 **Preferred on commits:** also put `Closes #N` in the first commit message when the fix starts. Commit alone is backup; the PR body is the contract.
 
-**Stacked / intermediate PRs** that do not merge into the default branch: use a plain `#N` reference in the body so the issue links without a false close promise. Put `Closes #N` only on the PR that actually lands on the default branch.
+**Stacked / intermediate PRs** that do not merge into the default branch: use a plain `#N` reference in the body so the issue links without a false close promise. Put `Closes #N` only on the PR that lands on the default branch.
 
 **Not enough:** a Development "related" link with no closing keyword. **Not enough:** closing the PR without merging.
 

package/.agents/skills/orchestrator/SKILL.md

@@ -24,7 +24,7 @@ than a solo frontier agent held to the same verification rigor, with
 84-98% of the team's input tokens billed at the worker rate.
 
 Under this skill the session is the orchestrator. It spawns and resumes
-executor subagents — `clean-coder` and the like — and those executors do
+executor subagents through `pstack:poteto-agent`, and those executors do
 every bit of the execution: the code edits, the build runs, the test
 runs. The orchestrating session drives the plan, keeps the run artifacts
 and the ledger current, and answers executor consults. Hard questions
@@ -190,7 +190,7 @@ Return: status, artifact paths, blockers — nothing else.
   unit that fits one sentence plus pointers, has one mechanical
   done-check, and needs no mid-run clarification. A task that does not
   fit gets split in the plan — never padded into a longer prompt.
-  Explore fan-outs run tiny; a `clean-coder` assignment can carry a
+  Explore fan-outs run tiny; a `pstack:poteto-agent` assignment can carry a
   whole scoped feature.
 - **Focused tickets are the house convention.** One mechanical done-check
   per ticket; thick context lives in the assignment file, not the ticket
@@ -204,10 +204,9 @@ Return: status, artifact paths, blockers — nothing else.
 - **Resume with a thin next-slice ticket.** A warm agent already holds
   the assignment's thick context, so its next ticket names only the next
   slice of work and the done-check — it does not restate the assignment.
-- **Do not restate what the agent definition carries.** The routing
-  table picks the definition, and `clean-coder` already holds the code
-  discipline. The ticket adds the task, the pointers, and the consult
-  block only.
+- **Keep the task brief specific.** The `pstack:poteto-agent` definition
+  carries poteto-mode style. The ticket adds the task, the pointers, the
+  task-specific instructions, and the consult block.
 - **The consult block is pasted, assembled text.** Assemble it at ticket
   write time from the parts in
   [`reference/executor-consult-block.md`](reference/executor-consult-block.md)
@@ -215,16 +214,15 @@ Return: status, artifact paths, blockers — nothing else.
 
 ## Workflow Agent Routing
 
-Every delegated task runs through a workflow-backed agent invocation. Do
-not spawn a flat subagent directly when a workflow invocation or
-workflow resume is available.
+Every delegated task uses `pstack:poteto-agent` with a task-specific prompt.
+Resume an existing agent when its context matches the task.
 
 | Work | Agent type | Model |
 |---|---|---|
-| Feature, bug, and refactor coding | `clean-coder` | `sonnet` on a Claude host; the sonnet-equivalent id the worker-model resolver prints on a third-party host |
-| Review and verification | `code-quality-agent` | `sonnet` on a Claude host; the sonnet-equivalent id the worker-model resolver prints on a third-party host |
-| Script runs, GitHub posting, and backfill driving | `general-purpose` runner | `sonnet` on a Claude host; the sonnet-equivalent id the worker-model resolver prints on a third-party host |
-| PR descriptions | `pr-description-writer` | `haiku`, with file-list grounding check |
+| Feature, bug, and refactor coding | `pstack:poteto-agent` | `sonnet` on a Claude host; the sonnet-equivalent id the worker-model resolver prints on a third-party host |
+| Review and verification | `pstack:poteto-agent` | `sonnet` on a Claude host; the sonnet-equivalent id the worker-model resolver prints on a third-party host |
+| Script runs, GitHub posting, and backfill driving | `pstack:poteto-agent` with an execution brief | `sonnet` on a Claude host; the sonnet-equivalent id the worker-model resolver prints on a third-party host |
+| PR descriptions | `pstack:poteto-agent` | `haiku`, with file-list grounding check |
 | Fan-out searches and checklist verification reads | `Explore` | `haiku`; use `sonnet` when judgment-heavy |
 
 Every row that edits code, runs a build, or runs a test is a coding row.
@@ -234,8 +232,8 @@ the worker model; the per-spawn `model:` field does.
 
 Routing rules:
 
-- Each row spawns workflow-backed with a ticket; the routing row and the
-  ticket together carry the agent type, model, task, and return
+- Each row spawns `pstack:poteto-agent` with a ticket; the routing row and
+  the ticket together carry the agent type, model, task, and return
   contract. A coding task category is never served by a different tier
   as a cost call — the table is the contract.
 - **Fail closed on a Claude host.** When `sonnet` cannot be spawned, use
@@ -255,8 +253,11 @@ Routing rules:
   detection system, with no second one.
 - Resume a warm workflow agent before creating a new workflow run when
   the warm agent holds the relevant context.
-- Review and verification workflows apply the [review guide](../reviews/SKILL.md#review-workflow).
-- PR-description workflows include the actual changed-file list in the
+- When a native subagent spawn is the advisor path, set
+  `flags: ["--advisor"]` with the Astra model. This is the explicit hook
+  bypass for advisor work. Do not add the flag to worker spawns.
+- Review and verification workflows apply the [review guide](../e-code-review/SKILL.md).
+- PR-description workflows include the changed-file list in the
   prompt and verify the final body against that file list before posting
   or returning it.
 - Exploration workflows return file paths, line numbers, and direct
@@ -274,7 +275,7 @@ Routing rules:
   background spawn — keep the `agentId` (format `a...-...`) from the
   spawn result so `SendMessage` can reach that agent later.
 - **Spawn a fresh agent only when** no existing agent holds relevant
-  context, or a genuine task switch needs a clean context.
+  context, or a task switch needs a clean context.
 - **Reuse is a cost rule, not a correctness dependency.** The run
   artifacts keep every executor replaceable (Run state section).
 - **Name the agent to resume.** When a PLAN from this session fits