feat(install): add grok-bot install target for agent-data/workflows

[Sergio Sisternes (sergio-sisternes-epam)]

Description

Adds a first-class grok-bot install target for Grok Bot agent skills.
Skill packages deploy to agent-data/workflows/<skill-name>/SKILL.md at
project scope and ~/agent-data/workflows/<skill-name>/SKILL.md at user
scope (--global), so Grok Bot reads them directly without a manual
copy or symlink from .agents/skills/ or apm_modules. The target is
stable and explicit-only (select with --target grok-bot); existing
grok-build and grok-cloud (.grok/) targets are unchanged.

Issue and approved scope

Issue: #3083

Human scope-approval comment: #3083 (comment)

This PR completes the accepted scope.

Type of change

• Bug fix
• New feature
• Documentation
• Maintenance / refactor

Testing

• Tested locally
• All existing tests pass
• Added tests for new functionality (if applicable)

Ran: uv run --extra dev ruff check src/ tests/,
uv run --extra dev ruff format --check src/ tests/,
uv run --extra dev python -m pylint --disable=all --enable=R0801 --min-similarity-lines=10 --fail-on=R0801 src/apm_cli/,
bash scripts/lint-auth-signals.sh, and the target-resolution/install test
suites (tests/unit/core/test_target_catalog.py,
tests/unit/core/test_scope.py, tests/integration/test_grok_bot_target.py,
tests/integration/test_hermes_target.py,
tests/unit/commands/test_targets_command.py,
tests/unit/test_lockfile_enrichment.py) -- all passed.

Spec conformance (OpenAPM v0.1)

If this PR changes behaviour that an OpenAPM v0.1 req-XXX covers,
confirm the three-step ritual in the
development guide:

• Spec edit: docs/src/content/docs/specs/openapm-v0.1.md updated
  (new/changed <a id="req-XXX"></a> anchor + prose + Appendix C
  row).
• Manifest edit: docs/src/content/docs/specs/manifests/openapm-v0.1.requirements.yml
  updated.
• Test edit: a @pytest.mark.req("req-XXX") test under
  tests/spec_conformance/ added or extended.
• CONFORMANCE.{md,json} regenerated via
  uv run --extra dev python -m tests.spec_conformance.gen_statement
  and committed.
• OpenAPM: editorial fold to req-tg-001's explicit-only enumeration (0.1.45), no new normative statement, count unchanged at 128.

Fixes #3083

[Sergio Sisternes (sergio-sisternes-epam)]

APM Review Panel: ship_with_followups

Adds a stable, explicit-only grok-bot install target that deploys skills to agent-data/workflows/ so Grok Bot can load them without a manual copy -- closes #3083 with catalog, profile, docs, and integration coverage aligned to the hermes/agent-skills pattern.

cc Sergio Sisternes (@sergio-sisternes-epam) Daniel Meppiel (@danielmeppiel) -- a fresh advisory pass is ready for your review.

This PR is a clean first-class target addition. It extends the single catalog owner (TARGET_CAPABILITIES + KNOWN_TARGETS), marks the target explicit_only (so all does not silently expand into it), remaps .github/skills/ via _CROSS_TARGET_MAPS, and ships integration tests that prove project and --global deploy paths land at agent-data/workflows/<name>/SKILL.md. Docs and CHANGELOG were updated in the same change. No blocking-severity findings; the follow-ups below are judgment calls for the author and maintainer.

Aligned with: multi-harness / multi-host (skills-only Grok Bot runtime beside grok-build and grok-cloud); pragmatic-as-npm (explicit --target opt-in, not forced into all); OSS community-driven (CHANGELOG + targets-matrix entry for discoverability).

Growth signal. First-class grok-bot support closes the gap between Grok Bot's agent-data/workflows/ layout and APM's install pipeline -- a concrete adoption unlock for xAI/Grok Bot users who today copy or symlink skills by hand.

Panel summary

Persona	B	R	N	Takeaway
Python Architect	0	1	1	Catalog + TargetProfile follow hermes pattern; detect_target elif remains pre-existing debt.
CLI Logging Expert	0	0	0	No new logging/output surface beyond catalog description string.
DevX UX Expert	0	1	1	Explicit-only + skills-only is the right default; call out visible project-root agent-data/.
Supply Chain Security Expert	0	1	0	Same skill-trust model as peer targets; visible root raises accidental-commit risk -- document it.
OSS Growth Hacker	0	0	1	Solid adoption unlock; naming triad (grok-bot / grok-build / grok-cloud) stays clear.
Doc Writer	0	1	1	Reference docs + CHANGELOG land together; consider a one-liner on commit/gitignore posture.
Test Coverage Expert	0	1	0	Deploy + parser + cross-map coverage is strong; add a drop-target reconcile trap when convenient.
Auth Expert	--	--	--	inactive -- no auth/token/host surfaces touched.
Performance Expert	--	--	--	inactive -- catalog registration only; no hot-path complexity change.

B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.

Top 4 follow-ups

1. [DevX UX Expert] Document project-scope agent-data/ visibility -- The root is intentionally dotless (issue [FEATURE] Add install target for Grok Bot agent skills folder #3083). Add a one-line note in the grok-bot targets-matrix section on whether consumers typically commit agent-data/workflows/ or gitignore it, so first-time installers are not surprised by a new top-level directory.
2. [Supply Chain Security Expert] Same trust model, new writable root -- Skills under agent-data/workflows/ execute in the Grok Bot runtime. Confirm (in docs) that install still routes through the existing collision / path-security checks in BaseIntegrator so a malicious skill name cannot escape the workflows subtree.
3. [Test Coverage Expert] Drop-target reconcile regression trap -- Existing tests prove install lands files. A short follow-up that removes grok-bot from targets: (or reinstalls without it) and asserts reconcile removes ownership would close the uninstall half of the install contract.
4. [Python Architect] detect_target elif growth (pre-existing) -- This PR correctly adds two more elif arms. Not required here, but a later cleanup that dispatches via catalog membership would stop the chain from growing with every new explicit-only target.

Architecture

classDiagram
  class TargetCapability {
    <<Catalog entry>>
    +name
    +explicit_only
    +primitive_profile
  }
  class TargetProfile {
    <<Deploy shape>>
    +root_dir
    +primitives
    +detect_by_dir
    +user_root_dir
  }
  class PrimitiveMapping {
    +subdir
    +file_suffix
    +adapter
  }
  class TARGET_CAPABILITIES {
    <<single owner>>
  }
  class KNOWN_TARGETS {
    <<single owner>>
  }
  TARGET_CAPABILITIES *-- TargetCapability
  KNOWN_TARGETS *-- TargetProfile
  TargetProfile o-- TargetCapability : capability
  TargetProfile *-- PrimitiveMapping : primitives
  class GrokBotCapability {
    name = grok-bot
    explicit_only = True
  }
  class GrokBotProfile {
    root_dir = agent-data
    user_root_dir = agent-data
    detect_by_dir = False
  }
  GrokBotCapability --|> TargetCapability
  GrokBotProfile --|> TargetProfile
  class GrokBotCapability:::touched
  class GrokBotProfile:::touched
  class PrimitiveMapping:::touched

Loading

flowchart TD
  CLI["apm install --target grok-bot"] --> Detect["detect_target / TargetParamType"]
  Detect --> Catalog["TARGET_CAPABILITIES['grok-bot']\nexplicit_only=True"]
  Catalog --> Profile["KNOWN_TARGETS['grok-bot']\nroot_dir=agent-data"]
  Profile --> Scope{user scope?}
  Scope -->|project| Proj["project/agent-data/workflows/name/SKILL.md"]
  Scope -->|--global| Home["~/agent-data/workflows/name/SKILL.md"]
  Profile --> Map["_CROSS_TARGET_MAPS\n.github/skills/ -> agent-data/workflows/"]

Loading

Recommendation

Ship once CI is green. The change is narrowly scoped, catalog-owned, documented, and covered by integration tests for the two deploy paths that matter. Track the visibility/gitignore doc note and the drop-target reconcile trap as post-merge (or quick in-PR) follow-ups; neither is a correctness regression on the happy path this PR delivers.

---

Full per-persona findings

Python Architect

• [recommended] detect_target continues a hand-rolled elif chain for explicit-only targets at src/apm_cli/core/target_detection.py
  Pre-existing pattern; this PR adds grok-bot arms for --target and apm.yml. Catalog already owns explicit_only; a later dispatch via membership would remove the fork.
  Suggested: Follow-up PR: resolve explicit-only targets from EXPLICIT_ONLY_TARGETS / TARGET_CAPABILITIES instead of per-slug elif.
• [nit] TargetProfile comment block is thorough and matches hermes/agent-skills modeling -- keep as the template for the next skills-only target.

CLI Logging Expert

No findings.

DevX UX Expert

• [recommended] Project-scope deploy creates a visible top-level agent-data/ directory at src/apm_cli/integration/targets.py
  Intentional per [FEATURE] Add install target for Grok Bot agent skills folder #3083, but first-run users may wonder whether to commit it. Docs should say so explicitly next to the deploy-directory bullet.
  Suggested: One sentence in targets-matrix grok-bot section: commit vs gitignore guidance.
• [nit] Help-text exclusion lists and install flag docs correctly name grok-bot beside hermes -- good parity.

Supply Chain Security Expert

• [recommended] New writable root agent-data/workflows/ inherits skill-execution trust at src/apm_cli/integration/targets.py
  Same BaseIntegrator collision and path checks should apply; confirm in review that skill-name sanitization still prevents ../ escapes into sibling trees under agent-data/. Document that grok-bot skills are trusted the same way as hermes/agent-skills.
  Suggested: Spot-check BaseIntegrator path join for the new root; add a one-liner to the grok-bot doc section on trust posture.

OSS Growth Hacker

• [nit] CHANGELOG Unreleased entry is clear and issue-linked -- good release-note seed for the next cut.

Auth Expert -- inactive

No auth, token, host-classification, or credential surfaces touched (target catalog / profile / docs / tests only).

Doc Writer

• [recommended] Add commit/gitignore posture for project-scope agent-data/ in docs/src/content/docs/reference/targets-matrix.md
  Deploy directory and file conventions are documented; the missing reader question is "do I check this in?".
• [nit] packages/apm-guide/.../commands.md cell is already enormous; the grok-bot clause is correct but hard to scan -- acceptable for this PR.

Test Coverage Expert

• [recommended] Missing drop-target / reconcile coverage for grok-bot at tests/integration/test_grok_bot_target.py
  Install happy-path and parser constants are well covered (integration-with-fixtures). The install contract also promises reconcile when a target is dropped from targets:; no assertion defends that half for grok-bot yet.
  Proof (missing at): tests/integration/test_grok_bot_target.py -- proves: dropping grok-bot from targets reconciles away owned agent-data/workflows artifacts [multi-harness-support,devx]
  Suggested: Mirror hermes reconcile coverage with one test that installs, removes the target, reinstalls, and asserts ownership cleanup.

Performance Expert -- inactive

Catalog and profile registration only; no change to download, cache, materialization, or algorithmic hot paths.

_{This panel is advisory. It does not block merge. Re-apply the
panel-review label after addressing feedback to re-run.}

[Copilot]

Copilot review overview

🟡 Changes recommended

The target is omitted from apm targets, while documentation, behavioral coverage, and changelog updates remain incomplete.

Review effort: Balanced
Findings: 2 · 3

Open (5)

• Add behavioral coverage for grok-bot target mapping · New
• Include grok-bot in apm targets projections and coverage · New
• Use the pull request reference in the changelog bullet · New
• Update documentation target lists to include grok-bot · New
• Update duplicate install rows to include grok-bot · New

What changed in this PR

Adds the stable, explicit-only grok-bot target requested by #3083, deploying skills to agent-data/workflows/ at project and user scope.

Changes:

• Registers target detection, capabilities, deployment paths, and lockfile mapping.
• Adds install and catalog coverage.
• Updates CLI documentation and changelog.

File	Description
src/​apm_cli/​core/​target_catalog.py	Registers the target capability.
src/​apm_cli/​core/​target_detection.py	Adds parsing and descriptions.
src/​apm_cli/​integration/​targets.py	Defines project/user skill paths.
src/​apm_cli/​bundle/​lockfile_enrichment.py	Adds cross-target skill mapping.
tests/​integration/​test_grok_bot_target.py	Tests parsing and deployment.
tests/​integration/​test_global_scope_e2e.py	Allows the dotless user root.
tests/​unit/​core/​test_target_catalog.py	Updates catalog expectations.
tests/​unit/​core/​test_target_catalog_owner_invariant.py	Updates ownership guard data.
tests/​unit/​core/​test_scope.py	Updates known-target coverage.
tests/​unit/​test_cli_consistency.py	Updates exclusion help coverage.
docs/​src/​content/​docs/​reference/​targets-matrix.md	Documents target capabilities.
docs/​src/​content/​docs/​reference/​manifest-schema.md	Adds the manifest target slug.
docs/​src/​content/​docs/​reference/​cli/​install.md	Documents install selection.
docs/​src/​content/​docs/​reference/​cli/​deps.md	Documents update selection.
docs/​src/​content/​docs/​reference/​cli/​compile.md	Documents no-op compilation.
docs/​src/​content/​docs/​concepts/​primitives-and-targets.md	Adds the target to the conceptual catalog.
packages/​apm-guide/​.apm/​skills/​apm-usage/​commands.md	Adds install guidance.
packages/​apm-guide/​.apm/​skills/​apm-usage/​dependencies.md	Adds dependency-routing guidance.
CHANGELOG.md	Announces the target.

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

Default output now exposes debug details, target metadata is misclassified, and the implementation exceeds the approved compatibility scope.

8 open findings

• Incorrectly infers meta-targets from shared .agents paths · New
• Scope compatibility expansion to grok-bot or obtain approval · New
• Keep detailed install errors behind the verbose flag · New
• Correct changelog description of explicit target failures · New
• Clarify manifest-wide versus explicit subtree failure behavior · New
• Include agent-skills in the explicit-only target list · New
• Update OpenAPM conformance for the req-tg-001 change · New
• Add architecture registry and linter guards for skills-root ownership · New

5 resolved since last review

• Include grok-bot in apm targets projections and coverage
• Add behavioral coverage for grok-bot target mapping
• Update duplicate install rows to include grok-bot
• Update documentation target lists to include grok-bot
• Use the pull request reference in the changelog bullet

🧠 Review effort: Balanced