claude-dev-env 8.2.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}/code-quality-agent.md

@@ -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
 

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:
 

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/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
 

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,6 +253,9 @@ 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.
+- 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

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

@@ -79,6 +79,8 @@ reports and adds nothing further.
      Claude host, or the resolver-printed sonnet-equivalent id on a
      third-party host, and fails closed — see Workflow Agent Routing in
      [`skills/orchestrator/SKILL.md`](../orchestrator/SKILL.md#workflow-agent-routing).
+     Advisor spawns use `flags: ["--advisor"]` only when they intentionally
+     select Astra.
    - **Focused tickets.** One mechanical done-check per ticket; resume a
      warm agent with a thin next-slice ticket rather than a fresh cold
      spawn, and keep thick context in the assignment file.

package/.agents/skills/pull-request/SKILL.md

@@ -38,8 +38,9 @@ Use this skill for one pull request action:
 - Submit a pull request review.
 - Recover one selected legacy author record before the action.
 
-Send issue create, edit, and comment work to `issue-tracker`. Send review and
-fix-loop work to `e-code-review`. Send commits to `source-command-commit`.
+Send issue create, edit, and comment work to `pstack:poteto-agent` with the
+`issue-tracker` skill and one action. Send review and fix-loop work to
+`e-code-review`. Send commits to `source-command-commit`.
 
 Require one repository and one action target. Stop before author lookup or
 network work when the repository, pull request, action, author, or required
@@ -73,9 +74,9 @@ current process environment.
 
 | Skill | When | Produces | If missing |
 |---|---|---|---|
-| `pr-description-writer` | Create or a full body rewrite, when you want the body drafted for you | A reviewed title and body file | Write the title and body yourself |
+| `pstack:poteto-agent` with `pull-request` instructions | Create or a full body rewrite, when you want the body drafted for you | A reviewed title and body file | Write the title and body yourself |
 | `privacy-hygiene` | Before any durable GitHub post | A clean body and repository privacy sweep | Stop before publication and report the missing gate |
-| `issue-tracker` | Issue create, edit, or comment requests | Issue state and issue URLs | Route the request there. |
+| `pstack:poteto-agent` with `issue-tracker` | Issue create, edit, or comment requests | Issue state and issue URLs | Load the skill in this session. |
 | `e-code-review` | Review or review/fix loop requests | Structured findings or a clean review result | Route the request there. |
 | `source-command-commit` | Commit or push requests | A verified commit or pushed branch | Route the request there. |
 
@@ -98,10 +99,15 @@ request target. Create actions publish drafts. Record the target before any writ
 ### 2. Author the title and body
 
 For create and full body rewrite, write the title and a body file, or invoke
-the installed `pr-description-writer` to draft them from the diff. A comment or
+`pstack:poteto-agent` with the diff-specific writing instructions to draft
+them. A comment or
 review may use a supplied body file when it does not rewrite the pull request
 description.
 
+Check each behavior claim against the final diff and verification evidence.
+Preserve whether a rule is added, removed, or narrowed, and distinguish tests
+added from tests run. Refresh these claims after a rebase or correction.
+
 ### 3. Run the local linter
 
 Resolve the active managed root (`CLAUDE_CONFIG_DIR` when set, `~/.claude`
@@ -153,6 +159,9 @@ Confirm the pull request URL and number, title, body, head SHA, and draft state.
 For comments and reviews, confirm the new remote entry. Report artifact URLs
 without exposing author values.
 
+Confirm the published claims still describe the verified head and preserve the
+scope of its evidence, including whether checks used saved artifacts or a new run.
+
 ## Exit handling
 
 Stop before network work when authoring, local validation, privacy, or author

package/.agents/skills/pull-request/reference/publication-tasks.md

@@ -6,7 +6,7 @@ reason when the task is conditional. This file is a task seed catalog, not a
 markdown progress board.
 
 1. Resolve one repository, action, and selected author. For create, resolve the source branch, base, and head. For other actions, resolve one existing pull request target. Create actions publish drafts.
-2. Record the title and body file for create or full body rewrite, written by you or drafted by `pr-description-writer`. Mark `N/A` for comment or review bodies that do not rewrite the pull request description.
+2. Record the title and body file for create or full body rewrite, written by you or drafted by `pstack:poteto-agent` with a PR-writing brief. Mark `N/A` for comment or review bodies that do not rewrite the pull request description.
 3. Validate every title, body, artifact, and local path input. Reject inline body input.
 4. Resolve the active managed root and run `<managed-root>/scripts/durable_post_lint.py` for the matching action. Record exit code `0` before credential lookup or network work.
 5. Run `privacy-hygiene` before the GitHub post and record its clean result.

package/.agents/skills/team-advisor/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: team-advisor
 description: >-
-  Bind one advisor, the built-in advisor tool or a warm session-advisor, and
+  Bind one advisor, the built-in advisor tool or a warm `pstack:poteto-agent`, and
   consult it before substantive work, completion, commits, or when stuck.
   Triggers:
   'team-advisor', 'team advisor', 'second opinion', 'consult the advisor',
@@ -18,14 +18,14 @@ One warm advisor at the strongest tier this session can reach. This session is t
 |---|---|
 | [`docs/references/advisor-tool.md`](../../docs/references/advisor-tool.md) | **Consult cadence and weight.** When to call, the hard rule before first write, and how to treat advice. Read this for every consult. |
 | [`~/.claude/_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md) | **Bind and lifecycle.** Session identity, host detect, model floor, warm-up, CLI fallback. Its read map routes each moment to a `reference/` detail file. |
-| [`agents/session-advisor.md`](../../agents/session-advisor.md) | **Reply contract.** ENDORSE / CORRECTION / PLAN / STOP. SendMessage only. |
+| Installed `poteto-mode` skill | **Reply contract.** The advisor prompt carries ENDORSE / CORRECTION / PLAN / STOP. |
 | [`reference/advisor-docs-review.md`](reference/advisor-docs-review.md) | Anthropic advisor-tool source facts: measured effects, Sonnet steering, cost levers, failure modes. Background. Read it when tuning the bind, not on every consult. |
 
 ## Bind
 
 1. Name the session identity first (protocol **Host profiles**), then walk the model floor.
-2. Claude: when `advisor` is in this session's tool list, the built-in advisor tool is the advisor. Spawn nothing and call `advisor()` at each consult point. Otherwise spawn Fable in-session at `ADVISOR_EFFORT` (default low). When Fable is out of usage, bind Astra at the same effort. Codex: Astra in-session. Third-party: headless Fable then Astra. When the host's walk fails, fail closed.
-3. Name: `team-advisor-agent` on Claude (Agent spawn of `session-advisor`); a native Astra subagent on Codex; one CLI `session_id` on a third-party host via the protocol Claude-chain or Astra helper.
+2. Claude: when `advisor` is in this session's tool list, the built-in advisor tool is the advisor. Spawn nothing and call `advisor()` at each consult point. Otherwise spawn or resume `pstack:poteto-agent` at `ADVISOR_EFFORT` (default low) with the advisor response contract in the prompt. When the bound model is out of usage, use the configured fallback at the same effort. Codex: use the native advisor path. Third-party: use the headless advisor path. When the host's walk fails, fail closed.
+3. Name the warm instance `team-advisor-agent` and keep its advisor response contract in every first prompt. When a native Codex subagent spawn is the advisor path, pass `flags: ["--advisor"]` with Astra.
 4. Skip the multi-consumer "who you are" opener. This session is the sole consumer.
 5. When the bind or reply path fails, fail closed and report to the user. On a third-party host, only the bound advisor issues ENDORSE / CORRECTION / PLAN / STOP.
 

package/bin/install.agents-home.test.mjs

@@ -12,6 +12,7 @@ import {
     mkdirSync,
     mkdtempSync,
     readFileSync,
+    readdirSync,
     realpathSync,
     rmSync,
     writeFileSync,
@@ -34,38 +35,8 @@ const SHIPPED_SKILL_NAME = 'privacy-hygiene';
 const ELI5_SKILL_NAME = 'eli5';
 const E_CODE_REVIEW_SKILL_NAME = 'e-code-review';
 const REFERENCE_DIRECTORY_NAME = 'reference';
-const SHIPPED_AGENT_FILE_NAME = 'clean-coder.md';
-const SHIPPED_AGENT_FILE_NAMES = [
-    SHIPPED_AGENT_FILE_NAME,
-    'code-quality-agent.md',
-    'pr-description-writer.md',
-];
-const CLEAN_CODER_POLICY_REFERENCES = [
-    [
-        '<managed-root>/docs/CODE_RULES.md',
-        'packages/claude-dev-env/docs/CODE_RULES.md',
-    ],
-    [
-        '<managed-root>/hooks/blocking/code_rules_enforcer.py',
-        'packages/claude-dev-env/hooks/blocking/code_rules_enforcer.py',
-    ],
-    [
-        '<managed-root>/rules/code-standards.md',
-        'packages/claude-dev-env/rules/code-standards.md',
-    ],
-    [
-        '<managed-root>/rules/windows-filesystem-safe.md',
-        'packages/claude-dev-env/rules/windows-filesystem-safe.md',
-    ],
-    [
-        '<managed-root>/rules/gh-cli-conventions.md',
-        'packages/claude-dev-env/rules/gh-cli-conventions.md',
-    ],
-    [
-        '<managed-root>/rules/plain-illustrative-docstrings.md',
-        'packages/claude-dev-env/rules/plain-illustrative-docstrings.md',
-    ],
-];
+const SHIPPED_AGENT_FILE_NAME = 'AGENTS.md';
+const RETIRED_AGENT_FILE_NAMES = ['clean-coder.md', 'code-quality-agent.md', 'pr-description-writer.md'];
 const PERSONAL_SKILL_NAME = 'my-notes';
 const PREFLIGHT_PROPOSAL_FILE_NAME = 'preflight-proposal.md';
 
@@ -116,37 +87,48 @@ function assertProposalContractInstallation(installationPaths) {
     assert.equal(readFileSync(installedContractPath, 'utf8'), readFileSync(sourceContractPath, 'utf8'));
 }
 
-/**
- * @param {string} agentFilePath
- * @param {string} layoutName
- * @param {string} managedRoot
- * @returns {string[]}
- */
-function cleanCoderPolicyReferenceProblems(agentFilePath, layoutName, managedRoot) {
-    const agentBody = readFileSync(agentFilePath, 'utf8');
-    const missingReferences = [];
-    for (const [installedReference, sourceReference] of CLEAN_CODER_POLICY_REFERENCES) {
-        const eachReference = layoutName === 'source'
-            ? sourceReference
-            : installedReference;
-        const eachTargetPath = sourceReference.replace('packages/claude-dev-env/', '');
-        if (!agentBody.includes(eachReference)) {
-            missingReferences.push(eachReference + ' is absent');
-        }
-        const resolvedPath = layoutName === 'source'
-            ? join(PACKAGE_DIRECTORY, eachTargetPath)
-            : join(managedRoot, eachTargetPath);
-        if (!existsSync(resolvedPath)) {
-            missingReferences.push(layoutName + ': ' + resolvedPath);
-        }
-    }
-    return missingReferences.map((reference) => layoutName + ': ' + reference);
-}
 
 test('CONTENT_DIRECTORIES omits agents because that tree installs to the agents home', () => {
     assert.equal(CONTENT_DIRECTORIES.includes(MANAGED_AGENTS_DIRECTORY_NAME), false);
 });
 
+test('full install archives recorded retired agents and preserves third-party agents', () => {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-agent-retirement-'));
+    try {
+        runInstaller(homeDirectory, []);
+        const agentsDirectory = join(homeDirectory, '.agents', 'agents');
+        const retiredPath = join(agentsDirectory, 'clean-coder.md');
+        const pluginPath = join(agentsDirectory, 'poteto-agent.md');
+        const activePath = join(agentsDirectory, 'AGENTS.md');
+        const sourcePluginPath = join(PACKAGE_DIRECTORY, '.agents', 'agents', 'poteto-agent.md');
+        assert.equal(readFileSync(pluginPath, 'utf8'), readFileSync(sourcePluginPath, 'utf8'));
+        writeFileSync(retiredPath, 'recover this retired definition\n');
+        writeFileSync(pluginPath, 'preserve this plugin definition\n');
+        const manifestPath = join(homeDirectory, '.claude', '.claude-dev-env-manifest.json');
+        const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        manifest.files.push(retiredPath);
+        manifest.files.push(activePath);
+        writeFileSync(manifestPath, JSON.stringify(manifest));
+
+        runInstaller(homeDirectory, []);
+
+        assert.equal(existsSync(retiredPath), false);
+        assert.ok(existsSync(activePath));
+        const backupRoot = join(homeDirectory, '.claude', '.claude-dev-env-pruned');
+        const backupNames = readdirSync(backupRoot, { recursive: true });
+        const retiredBackup = backupNames.find(name => name.endsWith('clean-coder.md'));
+        assert.ok(retiredBackup);
+        assert.equal(readFileSync(join(backupRoot, retiredBackup), 'utf8'), 'recover this retired definition\n');
+        assert.equal(readFileSync(pluginPath, 'utf8'), 'preserve this plugin definition\n');
+        const updatedManifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        assert.equal(updatedManifest.files.includes(retiredPath), false);
+        runInstaller(homeDirectory, []);
+        assert.equal(readFileSync(pluginPath, 'utf8'), 'preserve this plugin definition\n');
+    } finally {
+        rmSync(homeDirectory, { recursive: true, force: true });
+    }
+});
+
 test('a full install writes skills and agents under .agents and points .claude at them', () => {
     const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-agents-home-'));
     const claudeHome = join(homeDirectory, '.claude');
@@ -201,18 +183,6 @@ test('a full install writes skills and agents under .agents and points .claude a
             readFileSync(lookupAgentFile, 'utf8'),
             readFileSync(canonicalAgentFile, 'utf8'),
         );
-        const sourceAgentFile = join(
-            resolvePackageManagedDirectory(
-                PACKAGE_DIRECTORY,
-                MANAGED_AGENTS_DIRECTORY_NAME,
-            ),
-            SHIPPED_AGENT_FILE_NAME,
-        );
-        const brokenPolicyReferences = [
-            ...cleanCoderPolicyReferenceProblems(sourceAgentFile, 'source', claudeHome),
-            ...cleanCoderPolicyReferenceProblems(canonicalAgentFile, 'installed', claudeHome),
-        ];
-        assert.deepEqual(brokenPolicyReferences, [], 'Clean Coder has broken policy references');
         assert.equal(realpathSync(lookupAgentFile), realpathSync(canonicalAgentFile));
         assert.equal(
             lstatSync(skillsInstallDirectory).isSymbolicLink(),
@@ -229,7 +199,7 @@ test('a full install writes skills and agents under .agents and points .claude a
     }
 });
 
-test('real installs place the Clean Coder in each active agents home', () => {
+test('installs omit retired agents in each active agents home', () => {
     const runRoot = mkdtempSync(join(tmpdir(), 'cdev-active-roots-'));
     const homeDirectory = join(runRoot, 'home');
     const configRoot = join(runRoot, 'config-profile');
@@ -283,7 +253,7 @@ test('real installs place the Clean Coder in each active agents home', () => {
                     ...eachInstallCase.environment,
                 },
             );
-            for (const eachAgentFileName of SHIPPED_AGENT_FILE_NAMES) {
+            for (const eachAgentFileName of RETIRED_AGENT_FILE_NAMES) {
                 const installedAgentPath = join(
                     eachInstallCase.agentsHome,
                     MANAGED_AGENTS_DIRECTORY_NAME,
@@ -291,30 +261,10 @@ test('real installs place the Clean Coder in each active agents home', () => {
                 );
                 assert.equal(
                     existsSync(installedAgentPath),
-                    true,
-                    `${eachInstallCase.name}: agent is under the active agents home`,
+                    false,
+                    `${eachInstallCase.name}: retired agent is absent`,
                 );
-                const installedAgentText = readFileSync(installedAgentPath, 'utf8');
-                assert.match(installedAgentText, /active managed root/i);
-                assert.match(installedAgentText, /active agents home/i);
-                assert.match(installedAgentText, /<managed-root>\//);
-                assert.match(installedAgentText, /<agents-home>\//);
             }
-            const installedCleanCoderPath = join(
-                eachInstallCase.agentsHome,
-                MANAGED_AGENTS_DIRECTORY_NAME,
-                SHIPPED_AGENT_FILE_NAME,
-            );
-            const policyReferenceProblems = cleanCoderPolicyReferenceProblems(
-                installedCleanCoderPath,
-                'installed',
-                eachInstallCase.managedRoot,
-            );
-            assert.deepEqual(
-                policyReferenceProblems,
-                [],
-                `${eachInstallCase.name}: Clean Coder has broken policy references`,
-            );
             assert.equal(
                 isDirectoryPointerTo(
                     join(eachInstallCase.managedRoot, MANAGED_AGENTS_DIRECTORY_NAME),