fraqtal/agentic-dev
Template
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

feat(skills): improve-codebase-architecture skill adapted for template-vertical

Browse Source 
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>
This commit is contained in:
Danijel Martinek
2026-05-13 17:30:59 +02:00
parent 769548c186
commit c85f96c62e
7 changed files with 391 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
.claude/hooks/prompt-context.sh
View File

@@ -43,6 +43,9 @@ 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) ==="