feat: the Engineer archetype — a hands-on pair-programming navigator

[mabry1985]

The Engineer archetype bundle: a hands-on pair-programming navigator (the operator drives and authors the fix; the agent orients, reproduces, points at evidence, reviews). It is the generic version of the navaEngineer agent.

• protoagent.bundle.yaml has these members:
  • builtins engineer (the navigator skill pack, new in core via feat(archetypes): the Engineer archetype — a hands-on pair-programming navigator protoAgent#3625), craft, friction, delegates;
  • terminal (terminal-plugin v0.4.1) and github (github-plugin v0.8.0), pinned as floors.
  • Recommended config: filesystem with per-command approval, read-only git auto-approved, the code pane, editor_command: zed, onboarding under ~/code from github.com/*, github.write: false, and friction.
  • Two optional Configure inputs: a starting checkout (goes to terminal.cwd and is registered as a managed project) and github.write.
  • The archetype block (soul_preset: engineer, icon Compass).
• README.md covers the navigator-vs-solver stance, citing arXiv 2607.26375 and Anthropic's AI-assistance coding-skills study. It also covers setup, the core floor ≥ 0.180.0, the defaults table, auto-approve / Allow-for-session, GitHub (the gh auth prerequisite and how to enable writes deliberately), the code pane, Zed Agent Panel wiring through protoagent-acp, and friction.
• scripts/ + .github/workflows/verify-bundle.yml are the pin lifecycle, built from the newest sibling shapes:
  • core's template workflow (with repository_dispatch) and bump_pins_pr.sh;
  • project-manager's verify_bundle.py (recommended config + contract);
  • design-system's floor-aware check_bundle_updates.py.

Core dependency: the builtin engineer plugin lands with protoLabsAI/protoAgent#3625 (unmerged). Against plain main, verify fails ("engineer: not found by the loader"). So the workflow now reads an optional repo variable PROTOAGENT_REF, currently refs/pull/3625/head. Delete that variable once #3625 merges so verify tracks main again. Local run against the #3625 branch:

installed terminal@501ef84cd7 (ref v0.4.1)
installed github@b21520a5cf (ref v0.8.0)
loaded terminal/github(15 tools)/engineer/craft/friction(3)/delegates(1)
view terminal '/plugins/terminal/view' -> 200
view github '/plugins/github/view' -> 200
view github '/plugins/github/new-issue' -> 200
OK — 2 member(s) installed+loaded, all declared views serve 200

The isolated-agent proof (a member created from this bundle, skills loaded, toolsets bound, one read-only onboarding turn) is in protoLabsAI/protoAgent#3625.

🤖 Generated with Claude Code

[protoreview]

QA panel review — WARN

code-review-structural · head 1452f1310cad · formal

⚠️ PR advanced 1 commit(s) during this round (1452f1310cad → b8e8428ec5af); 0 finding(s) in the delta were demoted to possibly addressed.

Low-risk first-content PR: five new files plus a README replacement. No correctness or removed-behavior issues surfaced. The one thing to fix before merge is the vacuous capability-contract check — verify_bundle.py reads archetype.requires_tools from the manifest, but the manifest never declares that key, so the check that was designed to catch the 2026-08-21 first-run banner passes silently. The missing tests/test_bump_pins_pr.py is a secondary gap: the script's own header and the workflow comment both claim automated coverage that isn't in the diff. No panel disagreement; all four findings are distinct and non-overlapping. Verification confirmed all four findings with no changes to severity or scope.

Findings

	Severity	Location	Finding	Verified
🟡	minor	protoagent.bundle.yaml:146	The capability-contract check in verify_bundle.py reads archetype.requires_tools from the manifest, but the manifest's archetype block declares no requires_too…	confirmed
🟡	minor	scripts/bump_pins_pr.sh:5	The script is described as 'a real, unit-tested script' with 'automated coverage' and names tests/test_bump_pins_pr.py by path, but no test file is in the PR —…	confirmed
⚪	nit	scripts/verify_bundle.py:34	Scratch temp directory is never cleaned up. In a CI environment that runs verification jobs repeatedly, these directories (containing installed plugin checkout…	confirmed
⚪	nit	.github/workflows/verify-bundle.yml:14	The workflow and bump_pins_pr.sh cross-reference a README section titled 'Pin-bump PR lifecycle', but the README's actual section heading is 'Pin lifecycle (AD…	confirmed

findings JSON (machine-readable)

[
  {
    "file": "protoagent.bundle.yaml",
    "line": 146,
    "severity": "minor",
    "category": "cross-file",
    "claim": "The capability-contract check in verify_bundle.py reads archetype.requires_tools from the manifest, but the manifest's archetype block declares no requires_tools key, so the check passes vacuously and never verifies that any tool is bound. Flagged by cross-file review; the script's own comment identifies this as the check that would have caught the 2026-08-21 first-run banner.",
    "evidence": "verify_bundle.py: `requires = list(((manifest_doc.get(\"archetype\") or {}).get(\"requires_tools\")) or [])` \u2014 the manifest's archetype block is: `archetype:\\n  label: Engineer\\n  icon: Compass\\n  soul_preset: engineer\\n  blurb: ...` with no requires_tools key.",
    "verdict": "confirmed",
    "note": "Manifest archetype block has only label/icon/soul_preset/blurb; the .get(\"requires_tools\") returns None \u2192 empty list \u2192 loop body never runs."
  },
  {
    "file": "scripts/bump_pins_pr.sh",
    "line": 5,
    "severity": "minor",
    "category": "tests",
    "claim": "The script is described as 'a real, unit-tested script' with 'automated coverage' and names tests/test_bump_pins_pr.py by path, but no test file is in the PR \u2014 the claimed coverage does not exist.",
    "evidence": "Header comment: `tests/test_bump_pins_pr.py drives this file directly, with `gh` stubbed on PATH and a real throwaway git repo \u2014 see that file's docstring for the harness shape.` No tests/ directory is present in the diff.",
    "verdict": "confirmed",
    "note": "Header names the test file; workflow says 'unit-tested \u2026 automated coverage'; diff adds no tests/ directory."
  },
  {
    "file": "scripts/verify_bundle.py",
    "line": 34,
    "severity": "nit",
    "category": "maintainability",
    "claim": "Scratch temp directory is never cleaned up. In a CI environment that runs verification jobs repeatedly, these directories (containing installed plugin checkouts) accumulate on disk indefinitely.",
    "evidence": "`tempfile.mkdtemp(prefix=\"bundle-verify-\")` creates a scratch directory that is never removed. Fix: replace with `tempfile.TemporaryDirectory(prefix=\"bundle-verify-\")` as a context manager wrapping the body of main.",
    "source": "protopatch",
    "verdict": "confirmed",
    "note": "mkdtemp at line 34; no rmtree/context-manager cleanup in any return path."
  },
  {
    "file": ".github/workflows/verify-bundle.yml",
    "line": 14,
    "severity": "nit",
    "category": "conventions",
    "claim": "The workflow and bump_pins_pr.sh cross-reference a README section titled 'Pin-bump PR lifecycle', but the README's actual section heading is 'Pin lifecycle (ADR 0049)' \u2014 the cross-reference does not match.",
    "evidence": "Workflow comment: `# until a maintainer approves it (see README.md \"Pin-bump PR lifecycle\",` \u2014 README heading: `## Pin lifecycle (ADR 0049)`",
    "verdict": "confirmed",
    "note": "Workflow line 14 and bump_pins_pr.sh both say 'Pin-bump PR lifecycle'; README heading is 'Pin lifecycle (ADR 0049)' \u2014 strings do not match."
  }
]

---

2 finding(s) downgraded to uncertain: the code they quote as evidence does not appear in the file at the reviewed head, nor in this PR's patch for it. A finding that cannot be grounded does not gate a merge (issue #25) — it still stands for a human to judge.

• protoagent.bundle.yaml (minor) — quoted evidence not found at this head: requires = list(((manifest_doc.get("archetype") or {}).get("requires_tools")) or []); archetype:\n label: Engineer\n icon: Compass\n soul_preset: engineer\n blurb: ...
• scripts/bump_pins_pr.sh (minor) — quoted evidence not found at this head: tests/test_bump_pins_pr.py drives this file directly, with

[protoreview]

QA panel review — PASS

code-review-structural · head 098d37d3034f · formal

Overall risk is low: the panel found no defects in this round, and the verifier confirmed there was nothing to verify (empty findings array). The one candidate finding from the structural pass (temp-dir cleanup in verify_bundle.py) was refuted by three independent LLM finders who confirmed a try/finally with shutil.rmtree is present in the current diff. The four minor/nit items carried from round 1 (vacuous capability-contract check, missing test file, temp-dir cleanup, README heading mismatch) are not carried into this round's findings; no blocker or major items are outstanding. No coverage gaps were flagged by the panel.

No findings — the review came back clean.

findings JSON (machine-readable)

[]

[protoreview]

Promoting the PASS verdict for head 098d37d3034f: all checks terminal-green, zero unresolved review threads. (approve-on-green)