Skip to content

feat(#188): /handover clone-first deep-dive prompt#192

Merged
atlas-apex merged 1 commit into
devfrom
feature/GH-188-handover-clone-prompt
May 9, 2026
Merged

feat(#188): /handover clone-first deep-dive prompt#192
atlas-apex merged 1 commit into
devfrom
feature/GH-188-handover-clone-prompt

Conversation

@atlas-apex

@atlas-apex atlas-apex commented May 9, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • Add Step 8 to /handover (between registry-append and validation) that offers (default-no) to clone the project into workspace/<name>/ for the LSP-aware deep-dive path used by /code-review, /threat-model, and /security-review.
  • Cost transparency in the prompt: ENABLE_LSP_TOOL=1, per-language plugin install (the adopter's problem — not bundled), disk cost (~tens of MB), gitignored status (workspace/*/), cross-project queries still need grep, and 30+s cold-start on large monorepos.
  • Branching: y runs git clone <repo-url> workspace/<name>, skips if the workspace already exists, and offers /threat-model as the natural next step. n / later / unrecognised input all skip silently with no side effects.
  • Doc note in docs/multi-project.md covering both the seed-per-project step and the skill-behaviour table row.

Implements #188 (LSP spike Phase 3 recommendation, Option 3 — interactive clone-first prompt).

Testing

  1. bash .claude/hooks/tests/test_handover_clone_prompt.sh — 18 cases pass:
    • 13 spec-shape assertions on SKILL.md (heading at the right step number, the five cost-transparency facts, three-option [y / n / later] shape, follow-up /threat-model suggestion, skip-if-exists branch, decline-silent semantics).
    • 5 runtime-shape cases against a mocked git binary: n -> no invocation, later -> no invocation, y -> exactly one git clone <url> workspace/<name>, y with pre-existing workspace -> no invocation, unknown input -> no invocation.
  2. for t in .claude/hooks/tests/test_*.sh; do bash "$t"; done — full hook test sweep, all 16 suites pass with no regressions.
  3. Smoke (manual): the actual /handover skill invocation against a public sample repo with the three operator paths (y, n, later) is the AC's smoke test and runs at adoption time — covered by the deterministic simulator in (1) for CI.

Glossary

Term Definition
LSP Language Server Protocol — gives editors and tools structured semantic queries (definitions, references, types) instead of grep-style text matching. Per-workspace scope by design.
ENABLE_LSP_TOOL=1 Env var the Claude Code harness reads to enable the LSP-backed code-navigation tool. Off by default; opting in requires the per-language plugin to be installed separately.
Deep-dive skills /code-review, /threat-model, /security-review — skills that benefit from LSP-aware navigation because they need to follow definitions and call sites across files.
workspace/<name>/ The per-project live working copy directory inside an apexyard fork. Each entry is a git clone of the project's own repo and is gitignored from the fork itself (workspace/*/).
Default-no prompt An interactive offer where the operator must type y explicitly to proceed; any other input (including silence / Enter / n / later / unrecognised) is treated as decline. The opposite shape from a default-yes prompt.
Skip-if-exists The clone path's idempotency safeguard: if workspace/<name>/ already contains a clone, the skill prints a confirmation and continues without re-cloning, avoiding a destructive overwrite.
Spec-shape test A test that asserts a markdown skill spec contains specific literal substrings at specific section ordinals. The skill itself is executed by the model, so the SKILL.md is the source of truth and content drift is the regression we catch.
Runtime-shape test A test that exercises a small bash simulator faithful to the spec's documented branches, against a mocked binary, to verify the operator-input -> side-effect contract holds without making any real network or filesystem changes.

Closes #188

@me2resh @claude
feat(#188): /handover offers clone-first deep-dive prompt
84b08a9 
- Add Step 8 to /handover SKILL.md: after registry append, offer
  (default-no) to clone the project into workspace/<name>/ for the
  LSP-aware deep-dive path used by /code-review, /threat-model,
  /security-review.
- Prompt explicitly surfaces ENABLE_LSP_TOOL=1, the per-language
  plugin install (adopter's problem, not bundled), disk cost,
  workspace/*/ gitignored status, cross-project grep caveat, and
  cold-start cost on large monorepos. Cost is owned, not assumed.
- y triggers git clone <repo-url> workspace/<name>; skip-if-exists;
  on success offer /threat-model as the natural next skill.
- n / later / unrecognised input all skip silently, no side effects.
- Update Rule #7 to reflect the explicit-opt-in clone path.
- Add test_handover_clone_prompt.sh — 13 spec-shape assertions on
  SKILL.md content (location, prompt text, cost-transparency facts)
  + 5 runtime-shape cases against a mocked git binary (n/later/y/
  pre-existing workspace/unknown input).
- Doc note in docs/multi-project.md (single-fork seed step + skill
  behaviour table row).

Closes #188

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
atlas-apex
atlas-apex commented May 9, 2026
View reviewed changes

@atlas-apex atlas-apex left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review: PR #192

Commit: 84b08a9171aedbc525d95e1b0e45a349780380b8

Summary

Adds a clone-first deep-dive prompt to /handover (Step 8) that offers — default-no — to clone the project into workspace/<name>/ for LSP-aware follow-up skills (/code-review, /threat-model, /security-review). Three-branch operator response (y / n / later), with n / later / unrecognised all skipping silently. Skip-if-exists guard wraps the clone. Cost-transparency block surfaces all five required facts. Step ordering renumbered cleanly (old 8 → 9, old 9 → 10, no off-by-one). Companion 18-case test (13 spec-shape + 5 runtime-shape with mocked git) plus a doc note in docs/multi-project.md.

Checklist Results

  • Architecture & Design: Pass — purely additive change to a markdown skill spec, no domain/infra layering involved
  • Code Quality: Pass — bash test is well-commented, isolates state in mktemp -d, mocks git cleanly, separates spec-shape from runtime-shape concerns
  • Testing: Pass — all 18 cases green locally; full hook test sweep (16 suites) green with no regressions
  • Security: Pass — no secrets, no shell-injection vectors in the test, git clone argv shape verified against the spec, mocked binary never reaches network
  • Performance: N/A — markdown spec + test
  • PR Description & Glossary: Pass — Summary, Testing, and a particularly thorough Glossary (LSP, ENABLE_LSP_TOOL, deep-dive skills, workspace//, default-no prompt, skip-if-exists, spec-shape vs runtime-shape tests)
  • Technical Decisions (AgDR): N/A for this PR — implements the recommendation from the LSP spike (issue #188 references the existing AgDR chain). No new technical decisions introduced; the prompt shape, default-no behaviour, and the spec-shape vs runtime-shape test split are all carry-forwards from the spike's Option 3.

Verification Performed

  1. Step ordering — confirmed ### 7 (registry) → ### 8 (clone offer, new) → ### 9 (validation, renumbered) → ### 10 (summary, renumbered). No duplicates, no skipped numbers.
  2. All 5 cost-transparency facts present in the prompt block: ENABLE_LSP_TOOL=1, "plugin install is your problem", gitignored + ~tens of MB disk, "Cross-project semantic queries still need grep", "Cold-start on large monorepos can be 30+ seconds".
  3. Three-branch response — y clones with exactly git clone <repo-url> workspace/<name> (runtime-accept-y test asserts argv match); n and later skip silently with no git invocation (both runtime tests green); unknown input treated as n.
  4. Skip-if-exists guard — [ -d "workspace/<name>" ] check wraps the clone; runtime-skip-if-exists test verifies no git invocation when the directory pre-exists.
  5. Test suite — bash .claude/hooks/tests/test_handover_clone_prompt.sh → Total: 18 passed, 0 failed. Full sweep across 16 hook test suites: all PASS, no regressions.
  6. Private-name scan — no private project references in any of the three touched files; only generic placeholders (example-app, marketing-site, some-org) and the framework's own slug (me2resh/apexyard) appear.
  7. CI — all 4 checks green (Verify Ticket ID, lychee, markdownlint-cli2, shellcheck .claude/hooks).
  8. PR body has Summary / Testing / Glossary, with the Glossary defining 8 terms.

Issues Found

None.

Suggestions (non-blocking)

  • The runtime simulator faithfully translates the spec but lives only inside the test file. If the spec's branching logic ever drifts (someone edits SKILL.md without updating the simulator), the runtime tests stay green against a stale simulator. The spec-shape tests catch most of this (they assert literal substrings in SKILL.md), but a future hardening would be a single source-of-truth bash snippet referenced from both the spec and the test. Not worth blocking on — the current split is documented as deliberate in the test header.
  • Tiny: the [y / n / later] brackets render as a markdown link target in some renderers. The fenced code block prevents that here, but worth keeping in mind if this prompt shape gets lifted into prose elsewhere.

Verdict

APPROVED (posted as comment — author cannot self-approve via gh API)

Reviewed by Rex (Code Reviewer Agent)
Reviewed commit: 84b08a9171aedbc525d95e1b0e45a349780380b8

@atlas-apex atlas-apex merged commit b79308d into dev May 9, 2026
4 checks passed
@atlas-apex atlas-apex deleted the feature/GH-188-handover-clone-prompt branch May 9, 2026 06:57
@atlas-apex atlas-apex mentioned this pull request May 9, 2026
Closed
6 tasks
me2resh added a commit that referenced this pull request Jun 5, 2026
@atlas-apex @me2resh @claude
feat(#188): /handover offers clone-first deep-dive prompt (#192)
550893f 
- Add Step 8 to /handover SKILL.md: after registry append, offer
  (default-no) to clone the project into workspace/<name>/ for the
  LSP-aware deep-dive path used by /code-review, /threat-model,
  /security-review.
- Prompt explicitly surfaces ENABLE_LSP_TOOL=1, the per-language
  plugin install (adopter's problem, not bundled), disk cost,
  workspace/*/ gitignored status, cross-project grep caveat, and
  cold-start cost on large monorepos. Cost is owned, not assumed.
- y triggers git clone <repo-url> workspace/<name>; skip-if-exists;
  on success offer /threat-model as the natural next skill.
- n / later / unrecognised input all skip silently, no side effects.
- Update Rule #7 to reflect the explicit-opt-in clone path.
- Add test_handover_clone_prompt.sh — 13 spec-shape assertions on
  SKILL.md content (location, prompt text, cost-transparency facts)
  + 5 runtime-shape cases against a mocked git binary (n/later/y/
  pre-existing workspace/unknown input).
- Doc note in docs/multi-project.md (single-fork seed step + skill
  behaviour table row).

Closes #188

Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

github-issue has-ticket

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@atlas-apex @me2resh