Danijel Martinek
c85f96c62e
Adapts mattpocock/skills/engineering/improve-codebase-architecture to
this repo. Four files at .claude/skills/improve-codebase-architecture/:
SKILL.md (104 lines):
- Explore -> Present candidates -> Grilling loop process
- "Hard constraints (do not propose violations)" section
enumerating ADRs 006/008/010/012/013/014/015/017/020/021 that
bound the design space
- Repointed at docs/glossary.md (not CONTEXT.md) and
docs/decisions/ (not docs/adr/)
- Exploration shortcuts specific to this repo: pnpm fallow,
pnpm coverage:diff, feature.manifest.ts, pnpm turbo boundaries
- Grilling loop side-effects target the right glossary section
and the next available ADR number (currently 022)
DEEPENING.md (93 lines):
- 4 dependency categories mapped to this repo's reality:
Cat 1 (in-process) -> entities/use-cases/presenters
Cat 2 (local-substitutable) -> our existing real + mock
adapter pattern (every port has both; mocks ARE stand-ins)
Cat 3 (remote but owned) -> cross-feature events via
IEventBus (E0/E1 rules)
Cat 4 (true external) -> Payload, Sentry/OTel, socket.io
(each constrained to its vendor-isolation seam by ADR)
- Seam discipline section recognises DI symbols + manifest entries
as concrete seams alongside .interface.ts files
- Testing strategy: replace not layer (matches ADR-020 L0 + L1)
- Conformance check command list at the end (typecheck, lint,
test --coverage, conformance, fallow:audit, coverage:diff)
INTERFACE-DESIGN.md (66 lines):
- Parallel sub-agent "Design It Twice" pattern preserved
- Every sub-agent brief MUST include glossary terms + ADR
constraints + manifest awareness
- Output items extended with "Manifest + binder impact" and
"ADR conflicts (if any)"
- Comparison axes include conformance impact + coverage delta
- Cross-feature moves flag release-please version-bump
implications (per ADR-021 commit-path targeting)
LANGUAGE.md (79 lines):
- Matt's 7 abstract terms preserved (module, interface,
implementation, depth, seam, adapter, leverage, locality)
- New "Mapping to this repo's identifiers" table — abstract
term -> concrete file shape (e.g. seam -> *.interface.ts +
DI symbol + manifest entry + <gen:*> anchor)
- Rejected framings extended with our reserved meanings
("boundary" stays the ESLint workspace-tag term; "service"
stays the DI port term)
Per user follow-up: vocabulary anchored so that "module" defaults
to "feature" in this repo (since features are our primary unit of
organisation). Abstract refactor sense survives only when the cross-
scale abstraction is the point. Glossary.md updated:
- "Feature" entry adds the "module = feature in refactor sense"
cross-link
- New "Architecture refactor vocabulary" section with 9 terms
(Module, Interface (refactor sense), Implementation, Depth,
Seam, Adapter, Leverage, Locality, Deletion test, Deepening)
— all framed so feature is the primary instance
- Flagged ambiguities entry for "module" rewritten to capture the
three coexisting senses (workspace package / Node ESM / refactor
vocabulary defaulting to feature); new entries for "seam" and
"adapter" to prevent drift with the existing "boundary" / "service"
/ "scope" reservations
Hooks updated:
- session-start.sh skills line lists the new skill
- prompt-context.sh adds a 10th keyword group firing on
refactor / deepening / shallow / architecture / seam / adapter /
interface design / design it twice — inject points at SKILL.md
+ summarises the vocabulary and hard constraints
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
56 lines
4.7 KiB
Bash
Executable File
56 lines
4.7 KiB
Bash
Executable File
#!/usr/bin/env bash
|
|
# Tier 2 — injects relevant ADR + workflow pointers when the user's prompt
|
|
# mentions concepts covered by an ADR or a hard ordering rule.
|
|
# stdout is appended to the agent's context for this turn.
|
|
|
|
set -euo pipefail
|
|
|
|
input=$(cat)
|
|
prompt=$(printf '%s' "$input" | jq -r '.prompt // ""' | tr '[:upper:]' '[:lower:]')
|
|
|
|
inject=()
|
|
|
|
if echo "$prompt" | grep -qE 'event|publish|consume|cross-feature|job queue'; then
|
|
inject+=('Events/jobs: ADR-015 + docs/guides/events-and-jobs.md. Rules E0 (events for cross-feature only), E1 (handlers private), J0 (jobs for deferred work).')
|
|
fi
|
|
if echo "$prompt" | grep -qE 'realtime|socket\.io|channel|broadcast|presence'; then
|
|
inject+=('Realtime: ADR-016 + docs/guides/realtime.md. Rules R0 (state delivery only), R1 (handlers private), R2 (socket.io in core-realtime only).')
|
|
fi
|
|
if echo "$prompt" | grep -qE 'audit|compliance|gdpr|dpa|erasure'; then
|
|
inject+=('Audit: ADR-018 + docs/guides/audit-and-compliance.md. Optional core; scaffold with pnpm turbo gen core-package audit.')
|
|
fi
|
|
if echo "$prompt" | grep -qE 'sentry|otel|opentelemetry|tracing|instrumentation|pii|scrub'; then
|
|
inject+=('Instrumentation: ADR-014 (interfaces) + ADR-017 (OTel migration). PII rules non-negotiable: sendDefaultPii=false, server-side scrub at OTel processor layer.')
|
|
fi
|
|
if echo "$prompt" | grep -qE 'use case|use-case|controller|repository|feature\.manifest|new feature|scaffold'; then
|
|
inject+=('Manifest-first ordering: (1) manifest → (2) contracts (xInputSchema, xOutputSchema, IXUseCase) → (3) tests (red) → (4) impl (green). Use pnpm turbo gen feature/event/job/realtime — never hand-roll.')
|
|
fi
|
|
if echo "$prompt" | grep -qE 'prd|epic|story|task|sandcastle|dispatch|orchestrat'; then
|
|
inject+=('Workflow: docs/architecture/agent-first-workflow-and-conformance.md + ADR-019. PRDs live in docs/work/prds/ — use the to-prd skill. Stress-test plans with grill-with-docs.')
|
|
fi
|
|
if echo "$prompt" | grep -qE 'di container|inject|bind-production|bind-dev-seed|symbols'; then
|
|
inject+=('DI: ADR-008 (per-feature containers). Binders take ctx from core-shared/di. Use .toDynamicValue() for factory bindings. Tests inject mocks directly — no container rebinding.')
|
|
fi
|
|
if echo "$prompt" | grep -qE 'boundary|boundaries|cross-package|cross feature'; then
|
|
inject+=('Boundaries: ADR-006 + ADR-010. Five tags (app|core|core-composition|feature|tooling). Features may only depend on core + tooling. Enforced by ESLint + Turborepo boundaries.')
|
|
fi
|
|
if echo "$prompt" | grep -qE 'coverage|uncovered|lcov|mutation|stryker|coverage band'; then
|
|
inject+=('Coverage: ADR-020 + docs/guides/coverage.md (cookbook). 4 layers — L0 vitest thresholds, L1 pnpm coverage:diff (cover-the-diff), L2 coverage/summary.json (committed trend), L3 pnpm mutate (Stryker on entities + use-cases). Manifest-driven: feature.manifest.ts coverage.bands is the single source of truth.')
|
|
fi
|
|
if echo "$prompt" | grep -qE 'commit|message|changelog|conventional'; then
|
|
inject+=('Conventional Commits (non-negotiable): <type>(<scope>): <imperative subject> (≤72 chars). Types: feat|fix|docs|style|refactor|test|chore|perf|ci|build|revert. Use `!` for breaking changes. Body explains WHY if non-obvious. Examples: feat(auth): hash password before persisting; refactor(docs)!: consolidate scaffolding into guides. See CLAUDE.md Key Conventions.')
|
|
fi
|
|
if echo "$prompt" | grep -qE 'release|version|bump|semver|tag\b'; then
|
|
inject+=('Releases: ADR-021 + docs/guides/releasing.md. Hybrid versioning — root template (template-v...) + 5 feature packages (auth-v..., blog-v..., etc.) version independently from 0.1.0. release-please reads Conventional Commits and opens a rolling release PR on every push to main; merging cuts per-package tags. Bump targeting is by commit-path, not (scope). Pre-1.0 policy: feat: -> patch, feat!: -> minor.')
|
|
fi
|
|
if echo "$prompt" | grep -qE 'refactor|deepening|shallow|architecture|seam|adapter|interface design|design it twice'; then
|
|
inject+=('Architecture refactors: invoke the improve-codebase-architecture skill (.claude/skills/improve-codebase-architecture/SKILL.md). Vocabulary: module (= feature by default in this repo) / interface / seam / adapter / depth / leverage / locality. Process: Explore -> Present numbered candidates -> Grilling loop. Hard constraints: respect ADRs 001-021 (factory-function shape, per-feature DI, manifest-first, generator-first, boundary tags, vendor isolation). Companion files: DEEPENING.md (dependency categories), INTERFACE-DESIGN.md (parallel sub-agent design pattern), LANGUAGE.md (vocab + this-repo identifier mapping).')
|
|
fi
|
|
|
|
if [ ${#inject[@]} -gt 0 ]; then
|
|
echo "=== context-relevant pointers (from .claude/hooks/prompt-context.sh) ==="
|
|
printf -- '- %s\n' "${inject[@]}"
|
|
fi
|
|
|
|
exit 0
|