Conversation
…ction - ADR-0001: Lazy skill loading via Claude Code hooks (SessionStart, FileChanged, CwdChanged) with thin spring-ask skill delegating to @pleaseai/ask. Replaces upfront /spring:install with on-demand resolution and zero-friction install. - ADR-0002: Three-tier version detection strategy: Bun static parsing (95%) -> opt-in build-tool fallback (~5%, consent-gated) -> --boot user override. Preserves library-layer I/O-free invariant; CLI used only as effective-pom expander, not evaluator. - ADR-0003: Extends Tier 1 to libs.versions.toml, gradle.properties, settings.gradle pluginManagement, and ~/.m2/~/.gradle cache lookup. Proposes spec amendments FR-12 through FR-17 for the build-file-detect-20260428 track.
…0003
Extends the build-file-detect-20260428 track to cover the additional static
parsing sources proposed in ADR-0003:
- FR-12: Gradle version catalog (libs.versions.toml) + gradle.properties
variable substitution.
- FR-13: settings.gradle(.kts) pluginManagement { plugins { ... } } block
as an additional version source ordered before per-module walk.
- FR-14: Maven external parent POM lookup via ~/.m2/repository cache;
falls back to unsupported with cache-miss reason if not present.
- FR-15: --boot override persistence at
~/.cache/pleaseai-spring/overrides.json keyed by sha256(project_dir).
Adds --boot and --clear-override CLI flags.
- FR-16: Published Gradle version catalog (from("g:a:v")) resolution
via cache-first lookup (~/.m2, ~/.gradle, ~/.cache), routing network
fetch through resolve.ts to preserve single-network-boundary invariant.
- FR-17: requires-build-tool reason taxonomy distinguishing patterns
needing JVM evaluation (buildSrc/, settings plugins, ${revision}) from
merely-unrecognized static patterns. Suggestion message includes both
the build-tool fallback consent flow (per ADR-0002) and --boot override.
Out-of-scope updates remove the now-in-scope items (libs.versions.toml,
pluginManagement) and clarify that build-tool evaluation execution is
owned by the Tier-2 follow-up track per ADR-0002.
Plan adds tasks T011–T016 implementing the new FRs, expanded dependency
graph, updated AC verification mapping, and a Decision Log entry citing
all three ADRs.
There was a problem hiding this comment.
5 issues found across 6 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name=".please/docs/tracks/active/build-file-detect-20260428/plan.md">
<violation number="1" location=".please/docs/tracks/active/build-file-detect-20260428/plan.md:114">
P2: Batch 4 incorrectly lists T016 as parallel with T013, but T016 depends on T013. This can mis-sequence implementation work.</violation>
</file>
<file name=".please/docs/tracks/active/build-file-detect-20260428/spec.md">
<violation number="1" location=".please/docs/tracks/active/build-file-detect-20260428/spec.md:50">
P2: FR-15 conflicts with the `DetectSource.file` contract by returning `overrides.json` for a global cache file that is outside the project root.</violation>
<violation number="2" location=".please/docs/tracks/active/build-file-detect-20260428/spec.md:51">
P2: FR-16 describes an incorrect path shape for `~/.gradle/caches/modules-2/files-2.1`; Gradle cache entries include a hash directory, so Maven-layout-only lookup will fail for cached catalogs.</violation>
</file>
<file name=".please/docs/decisions/0003-extended-static-parser-coverage.md">
<violation number="1" location=".please/docs/decisions/0003-extended-static-parser-coverage.md:144">
P3: Incorrect requirement reference (`FR-7`) makes the ADR internally inconsistent with the defined FR-12..FR-17 set.</violation>
</file>
<file name=".please/docs/decisions/0002-three-tier-version-detection.md">
<violation number="1" location=".please/docs/decisions/0002-three-tier-version-detection.md:60">
P2: Avoid a fixed `/tmp/effective.xml` output path for Tier-2 Maven fallback; it can cause race conditions and stale/cross-project reads under concurrent detections.</violation>
</file>
Architecture diagram
sequenceDiagram
participant Claude as Claude Code (Hooks)
participant Sync as sync.ts (Orchestrator)
participant Detect as detect.ts (Static Parser)
participant FS as Local Filesystem & Cache
participant Tools as Build Tools (Mvn/Gradle)
participant Ask as @pleaseai/ask (External API)
Note over Claude, Ask: NEW: ADR-0001/0002 Runtime Sync & Detection Flow
Claude->>Sync: NEW: Trigger via Hook (SessionStart / FileChanged)
Sync->>FS: NEW: Check ~/.cache/.../overrides.json (Tier 3)
FS-->>Sync: Return manual --boot override (if exists)
opt No Override Found
Sync->>Detect: NEW: Start Tier 1 Static Detection
Detect->>FS: CHANGED: Read build files + libs.versions.toml + gradle.properties
Note over Detect, FS: NEW: ADR-0003 External Cache Lookup
Detect->>FS: FR-14/16: Lookup ~/.m2/repository or ~/.gradle/caches
alt Static Match Found
Detect-->>Sync: Return version (Source: Static)
else Requires JVM (e.g., buildSrc, interpolation)
Detect-->>Sync: Return kind: 'unsupported' (requires-build-tool)
end
end
alt NEW: Tier 2 Escalation (ADR-0002)
Sync->>FS: Check for project-level consent
opt Consent Granted
Sync->>Tools: Exec 'mvn help:effective-pom' or Gradle init script
Tools-->>Sync: Return resolved build model
Sync->>Detect: Parse expanded tool output
Detect-->>Sync: Return version (Source: Build Tool)
end
end
Sync->>FS: NEW: Atomic write to ~/.cache/.../projects/<hash>.json
Sync-->>Claude: Hook complete (asyncRewake)
Note over Claude, Ask: NEW: ADR-0001 Lazy Delegation (at Query Time)
Claude->>FS: Read pinned version from project cache
Claude->>Ask: NEW: Fetch docs for @pleaseai/spring (version pinned)
Ask-->>Claude: Return relevant documentation snippets
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
Implements ADR-0001's hook-driven version sync model. New track defines `scripts/sync.ts` plus three Claude Code hooks (SessionStart, FileChanged, CwdChanged) that populate a per-project version cache at ~/.cache/pleaseai-spring/projects/<sha256(project_dir)>.json. The cache schema (FR-4) carries the resolved Boot version, component versions, source provenance, tier (1/2/3 per ADR-0002), and a needs_consent flag for Tier-2 escalation. Atomic temp+rename writes plus flock coordination handle concurrent invocations. asyncRewake: true is used exclusively to surface version *changes* to Claude (exit 2 with stdout summary). Same-version invocations exit 0 silently to avoid context pollution during edit-heavy sessions. Out of scope: the cache consumer (spring-ask-skill-20260429), Tier-2 build-tool execution (build-file-detect FR-17 / a follow-up track), override store CRUD (build-file-detect FR-15).
Implements the thin delegating skill side of ADR-0001's lazy-loading model. New track defines a single always-loaded skill at skills/spring-ask/SKILL.md plus a referenced library-mapping table. The skill: (a) detects Spring-related questions via its description matcher, (b) reads the per-project version cache produced by hook-sync-20260429, (c) maps question keywords to a Spring library identifier (Framework, Boot, Security, Data/JPA, Cloud, Batch, Integration, WebFlux, Reactor), and (d) delegates to @pleaseai/ask with the library identifier and version pinned from the cache. Refuses to silently answer in non-Spring projects (FR-7) — version correctness is preserved by reporting 'not a Spring project' rather than degrading to training-data knowledge. Cold-cache and stale-cache paths run sync.ts synchronously before delegating (FR-3, FR-8). The consent flow for Tier-2 (requires-build-tool) and Tier-3 (--boot override) is in the skill instructions rather than a separate command. Out of scope: the cache producer (hook-sync-20260429), @pleaseai/ask internals, per-component skill files, custom slash commands.
Updates the arch-md-v2-20260428 track to incorporate the lazy-loading direction concretized by ADR-0001/0002/0003 and the two new sibling tracks (hook-sync, spring-ask-skill). Spec changes: - § Sections to add: § Install Model (v2) must now cover the hook-driven sync model (SessionStart, FileChanged, CwdChanged -> scripts/sync.ts -> per-project cache); /spring:install becomes an opt-in pre-warmer rather than the default install path. - § Sections to add: optional § Three-Tier Detection subsection summarizing ADR-0002. - SC-5 expanded to require coverage of: thin spring-ask skill, hook model, three-tier detection, and the pre-warmer relationship. - Out of Scope: ADR creation now superseded by 2026-04-29 — ADRs 0001-0003 are landed and this track references them as authoritative input rather than producing new ADRs. - References: added ADR-0001/0002/0003 paths, hook-sync-20260429 and spring-ask-skill-20260429 sibling specs, and the Claude Code hooks documentation URL. Track registry: - tracks.jsonl: register hook-sync-20260429 and spring-ask-skill-20260429 under section: active. PRs both reference #8 (this PR) since they ship in the same review unit as the ADRs they implement.
There was a problem hiding this comment.
4 issues found across 8 files (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name=".please/docs/tracks/active/hook-sync-20260429/spec.md">
<violation number="1" location=".please/docs/tracks/active/hook-sync-20260429/spec.md:23">
P2: Cache contract is internally inconsistent: FR-4 omits the `unsupported` shape required by FR-5/AC-5.</violation>
</file>
<file name=".please/docs/tracks/active/spring-ask-skill-20260429/plan.md">
<violation number="1" location=".please/docs/tracks/active/spring-ask-skill-20260429/plan.md:46">
P2: T008 is described as optional, but Verification requires it unconditionally, which makes completion criteria ambiguous.</violation>
</file>
<file name=".please/docs/tracks/active/arch-md-v2-20260428/spec.md">
<violation number="1" location=".please/docs/tracks/active/arch-md-v2-20260428/spec.md:25">
P2: Use one consistent pre-warm command contract (`/spring:install --pre-warm` vs `/spring:install`) across the spec.</violation>
</file>
<file name=".please/docs/tracks.jsonl">
<violation number="1" location=".please/docs/tracks.jsonl:4">
P2: Issue is required by project config, but this track entry stores it as an empty string.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
Addresses 5 cubic-dev-ai bot review comments on PR #8 (all P2/P3 correctness and consistency issues): - plan.md (build-file-detect) Batch 4 dependency: T016 depends on T013, so it cannot run in parallel with T013. Re-phrased Batch 4 to: 'T012, T013, T015 in parallel; T016 starts after T011 + T013 land.' - spec.md (build-file-detect) FR-8 DetectSource.file contract: clarify that 'file' may be an absolute path for out-of-project sources (~/.m2 cache, ~/.gradle cache, ~/.cache/pleaseai-spring/*). Resolves inconsistency where FR-15's overrides.json source was outside the project root but the contract said 'relative path from project root'. - spec.md (build-file-detect) FR-15 source.file: use the full path '~/.cache/pleaseai-spring/overrides.json' rather than just 'overrides.json' to align with the clarified contract. - spec.md (build-file-detect) FR-16: Gradle cache layout actually includes a sha1-hash directory (...<version>/<hash>/<artifact>...), not the bare Maven layout. Updated the fixture description. - ADR-0002 Tier-2 Maven path: replace fixed '/tmp/effective.xml' with mktemp(1) (or per-project ~/.cache/pleaseai-spring/tier2/<hash>.xml) to avoid race conditions and cross-project reads under the lazy hook-driven invocation model from ADR-0001. - ADR-0003 line 144: incorrect requirement reference 'FR-7' corrected to 'FR-14 and FR-16' (the actual cache-layout-dependent requirements). All 5 are markdown documentation fixes; no code changes.
There was a problem hiding this comment.
1 issue found across 4 files (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name=".please/docs/tracks/active/build-file-detect-20260428/spec.md">
<violation number="1" location=".please/docs/tracks/active/build-file-detect-20260428/spec.md:39">
P2: The spec now conflates `~`-prefixed paths with absolute paths; this makes the `DetectSource.file` contract ambiguous for out-of-project sources.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
This was referenced Apr 29, 2026
Addresses 5 cubic-dev-ai bot review comments from the second review cycle (all P2 correctness/consistency issues): - hook-sync FR-4: extend cache schema to a tagged union covering all three DetectResult kinds (detected, unsupported, not-found) so the schema matches FR-5 and AC-5 requirements. Previously only the detected variant was shown despite FR-5/AC-5 referencing the unsupported shape. - spring-ask-skill plan T008/Verification: clarify that the eval-suite automated test is conditional (mirroring T008's 'optional if eval suite is not yet wired' qualification). Removes the contradiction where the verification was unconditional. - arch-md-v2 spec L25: align pre-warm command name to '/spring:install --pre-warm' for consistency with the immediately preceding paragraph in the same bullet. - tracks.jsonl + metadata.json: register issues #9 (hook-sync) and #10 (spring-ask-skill) created via gh issue create — config.yml declares 'issue_required: true', so empty 'issue' fields violated the project policy. Issue bodies link back to the originating ADRs and PR. - build-file-detect FR-8 DetectSource.file: remove ambiguity by specifying that '~/' prefix is readability shorthand only; the stored value is always a POSIX absolute path with $HOME expanded (e.g., '/Users/alice/.m2/...'). The literal '~/' never appears in the stored string. Two new GitHub issues created: #9, #10. All 5 cubic threads addressed.
Addresses 6 issues identified by /review:code-review (1 Critical + 5 Important; all P2/P3 documentation correctness/consistency issues). Iteration 2 review confirmed zero remaining issues. - build-file-detect spec.md FR-15: source.file example was using literal '~/.cache/...', contradicting FR-8's 'expand ~/ before storing' contract. Changed to expanded path '/home/<user>/.cache/...' with explicit illustration disclaimer and FR-8 cross-reference. - decisions/0003 ADR FR-14 description: was narrower than spec FR-14 (missing 'omits <relativePath>' trigger). Now matches spec text. - hook-sync-20260429 plan Overview: 'Issue: TBD' -> 'Issue: #9'. - spring-ask-skill-20260429 plan Overview: 'Issue: TBD' -> 'Issue: #10'. - hook-sync-20260429 spec Out-of-Scope: removed wrong attribution of Tier-2 execution to build-file-detect FR-17. Now coherent with build-file-detect's own OoS — both point to a follow-up track per ADR-0002. - spring-ask-skill plan Verification: added explicit Automated Tests bullets for FR-9 (no direct network) and FR-10 (no user-file writes) negative invariants. - hook-sync-20260429 plan Verification: added explicit Automated Tests bullet for FR-3 (atomic temp+rename write). 7 surgical text fixes; no semantic changes to the architecture. Internal /review:code-review iteration 2 confirmed clean.
There was a problem hiding this comment.
1 issue found across 5 files (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name=".please/docs/tracks/active/spring-ask-skill-20260429/plan.md">
<violation number="1" location=".please/docs/tracks/active/spring-ask-skill-20260429/plan.md:76">
P2: FR-9 verification is mapped to T006, but T006 only validates false-positive matching and does not check for direct network-call directives.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
Addresses 1 cubic-dev-ai bot review comment (P2, confidence 8): - spring-ask-skill-20260429/plan.md FR-9 verification bullet: the prior fix mapped FR-9 verification to T006, but T006 only validates false-positive description matching and does not check for direct network-call directives. Re-mapped to T001 (skill authoring) + T010 (documentation review), which actually own the network-invariant assertion. REVIEW_CUBIC_ENABLED=false; cubic local review skipped (cubic runs as a GitHub bot on push).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds the project's first three Architecture Decision Records (ADRs), applies the spec amendment proposed by ADR-0003 to the existing
build-file-detect-20260428track, creates two new tracks implementing ADR-0001/0002, and amendsarch-md-v2-20260428to absorb the hook-driven model.All changes are documentation/planning artifacts. No application code changes.
Commits
822c8ff96318e617 + T011T016 amendment7535e15889debc34931d8ADRs Introduced (commit 822c8ff)
/spring:installwith a thinspring-askskill plus Claude Code hooks (SessionStart,FileChanged,CwdChanged) delegating to@pleaseai/ask.--bootuser override (Tier 3).gradle/libs.versions.toml,gradle.properties,settings.gradle pluginManagement, and~/.m2/~/.gradlecache lookup.Spec Amendment: build-file-detect-20260428 (commit 96318e6)
Applies ADR-0003's proposed FR-12 through FR-17 to the affected track. Tasks T011~T016 added to the plan, AC-1 fixture matrix expanded with 8 new rows, References updated with ADR links.
New Tracks
hook-sync-20260429 (commit 7535e15)
Implements ADR-0001's hook-driven version sync. Defines
scripts/sync.ts, three Claude Code hook configurations, the per-project cache schema (~/.cache/pleaseai-spring/projects/<hash>.json), atomic write semantics, flock coordination, andasyncRewake: trueexit-code-2 contract for surfacing version changes to Claude.spring-ask-skill-20260429 (commit 889debc)
Implements the consumer side of ADR-0001 — a single thin skill at
skills/spring-ask/SKILL.mdplus a referenced library-mapping table. The skill reads the cache populated byhook-sync-20260429and delegates to@pleaseai/askwith the library identifier and version pinned. Refuses to silently answer in non-Spring projects to preserve version correctness.arch-md-v2 Amendment (commit 34931d8)
Updates
arch-md-v2-20260428spec to require coverage of the hook-driven model (per ADR-0001) and the three-tier detection strategy (per ADR-0002) in the new § Install Model (v2) section. Replaces the deferred ADR work with explicit references to the now-landed ADRs. Adds new sibling track and ADR references.tracks.jsonlupdated to register the two new tracks undersection: active.Track Registry State
After merge:
plugin-scaffold-20260428build-file-detect-20260428arch-md-v2-20260428hook-sync-20260429spring-ask-skill-20260429Notes
/spring:installnot removed: It survives as an opt-in--pre-warmmode for offline/CI scenarios, per ADR-0001.Checklist
decisions/index.mdregisters all three ADRsbuild-file-detect-20260428/spec.md+plan.mdamended (FR-1217, T011T016, AC matrix, References)hook-sync-20260429track created (spec + plan + metadata)spring-ask-skill-20260429track created (spec + plan + metadata)arch-md-v2-20260428/spec.mdamended (hook model coverage, ADR refs, scope updates)tracks.jsonlregisters both new tracks