{"id":"964fb51f-b867-49c8-ae8d-f20fb950e82c","shortId":"aSVY4N","kind":"skill","title":"improve-arch","tagline":"Find deepening opportunities in a codebase. Surface architectural friction and\npropose refactors that turn shallow modules into deep ones — small interface,\ndeep implementation. The aim is testability and AI-navigability.\nIf your project has a domain glossary (e.g. `CONTEXT.md`) ","description":"## Preamble\n\n```bash\neval \"$(~/.vibestack/bin/vibe-slug 2>/dev/null)\" 2>/dev/null || SLUG=\"unknown\"\n_LEARN_FILE=\"${VIBESTACK_HOME:-$HOME/.vibestack}/projects/${SLUG:-unknown}/learnings.jsonl\"\nif [ -f \"$_LEARN_FILE\" ]; then\n  _LEARN_COUNT=$(wc -l < \"$_LEARN_FILE\" 2>/dev/null | tr -d ' ')\n  echo \"LEARNINGS: $_LEARN_COUNT entries loaded\"\n  if [ \"$_LEARN_COUNT\" -gt 5 ] 2>/dev/null; then\n    ~/.vibestack/bin/vibe-learnings-search --limit 5 2>/dev/null || true\n  fi\nelse\n  echo \"LEARNINGS: none yet\"\nfi\n```\n\n# Improve Codebase Architecture\n\nSurface architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.\n\n## Glossary\n\nUse these terms exactly in every suggestion. Consistent language is the point — don't drift into \"component,\" \"service,\" \"API,\" or \"boundary.\" Full definitions in [LANGUAGE.md](LANGUAGE.md).\n\n- **Module** — anything with an interface and an implementation (function, class, package, slice).\n- **Interface** — everything a caller must know to use the module: types, invariants, error modes, ordering, config. Not just the type signature.\n- **Implementation** — the code inside.\n- **Depth** — leverage at the interface: a lot of behaviour behind a small interface. **Deep** = high leverage. **Shallow** = interface nearly as complex as the implementation.\n- **Seam** — where an interface lives; a place behaviour can be altered without editing in place. (Use this, not \"boundary.\")\n- **Adapter** — a concrete thing satisfying an interface at a seam.\n- **Leverage** — what callers get from depth.\n- **Locality** — what maintainers get from depth: change, bugs, knowledge concentrated in one place.\n\nKey principles (see [LANGUAGE.md](LANGUAGE.md) for the full list):\n\n- **Deletion test**: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.\n- **The interface is the test surface.**\n- **One adapter = hypothetical seam. Two adapters = real seam.**\n\nThis skill is _informed_ by the project's domain model. The domain language gives names to good seams; ADRs record decisions the skill should not re-litigate.\n\n## Process\n\n### 1. Explore\n\nIf the project has a domain glossary (e.g. `CONTEXT.md`) and ADRs (`docs/adr/`), read them first.\n\nThen use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:\n\n- Where does understanding one concept require bouncing between many small modules?\n- Where are modules **shallow** — interface nearly as complex as the implementation?\n- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no **locality**)?\n- Where do tightly-coupled modules leak across their seams?\n- Which parts of the codebase are untested, or hard to test through their current interface?\n\nApply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A \"yes, concentrates\" is the signal you want.\n\n### 2. Present candidates\n\nPresent a numbered list of deepening opportunities. For each candidate:\n\n- **Files** — which files/modules are involved\n- **Problem** — why the current architecture is causing friction\n- **Solution** — plain English description of what would change\n- **Benefits** — explained in terms of locality and leverage, and also in how tests would improve\n\n**Use the project's domain vocabulary (e.g. from `CONTEXT.md` if it exists) for domain concepts, and [LANGUAGE.md](LANGUAGE.md) vocabulary for the architecture.** If the domain says \"Order,\" talk about \"the Order intake module\" — not \"the FooBarHandler,\" and not \"the Order service.\"\n\n**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly (e.g. _\"contradicts ADR-0007 — but worth reopening because…\"_). Don't list every theoretical refactor an ADR forbids.\n\nDo NOT propose interfaces yet. Ask the user: \"Which of these would you like to explore?\"\n\n### 3. Grilling loop\n\nOnce the user picks a candidate, drop into a grilling conversation. Walk the design tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.\n\nSide effects happen inline as decisions crystallize:\n\n- **Naming a deepened module after a concept not yet documented?** If the project uses a `CONTEXT.md` domain glossary, add the term there. Create the file lazily if it doesn't exist.\n- **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there if the project uses one.\n- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _\"Want me to record this as an ADR so future architecture reviews don't re-suggest it?\"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons (\"not worth it right now\") and self-evident ones.\n- **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md).","tags":["improve","arch","vibestack","timurgaleev","agent-skills","ai-agents","claude-code","cursor-ide","developer-tools","kiro","mcp","prompt-engineering"],"capabilities":["skill","source-timurgaleev","skill-improve-arch","topic-agent-skills","topic-ai-agents","topic-claude-code","topic-cursor-ide","topic-developer-tools","topic-kiro","topic-mcp","topic-prompt-engineering","topic-slash-commands"],"categories":["vibestack"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/timurgaleev/vibestack/improve-arch","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add timurgaleev/vibestack","source_repo":"https://github.com/timurgaleev/vibestack","install_from":"skills.sh"}},"qualityScore":"0.457","qualityRationale":"deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 15 github stars · SKILL.md body (5,221 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:06:21.547Z","embedding":null,"createdAt":"2026-05-18T19:06:21.547Z","updatedAt":"2026-05-18T19:06:21.547Z","lastSeenAt":"2026-05-18T19:06:21.547Z","tsv":"'-0007':602 '/.vibestack/bin/vibe-learnings-search':92 '/.vibestack/bin/vibe-slug':47 '/dev/null':49,51,75,90,96 '/learnings.jsonl':62 '/projects':59 '1':345 '2':48,50,74,89,95,483 '3':632 '5':88,94 'across':294,438 'actual':761 'adapt':238,309,313 'add':693 'adr':334,357,573,581,595,601,614,734,744 'agent':365 'ai':33,129 'ai-navig':32,128 'aim':28,124 'also':526 'alter':229 'altern':792 'anyth':159,461 'api':150 'appli':456 'arch':3 'architectur':11,107,109,505,553,747 'ask':621 'avoid':769 'bash':45 'bear':730 'behaviour':203,226 'behind':204,662 'benefit':517 'bounc':394 'boundari':152,237 'bug':261,422 'call':428 'caller':173,250,296 'candid':485,495,577,640,725 'caus':507 'chang':260,516 'class':167 'clear':598 'code':193 'codebas':9,106,374,445 'complex':215,283,292,406,470 'compon':148 'concentr':263,469,477 'concept':392,546,681 'concret':240 'config':185 'conflict':574 'consist':139 'constraint':652 'context.md':43,355,540,690,714 'contradict':578,600 'convers':645,712 'count':69,81,86 'coupl':435 'creat':697 'crystal':674 'current':454,504 'd':77 'decis':336,673 'deep':21,25,121,208 'deepen':5,113,491,658,677,796 'definit':154 'delet':276,279,458,467 'depend':653 'depth':195,253,259 'descript':512 'design':648 'docs/adr':358 'document':684 'doesn':703 'domain':40,324,327,352,536,545,556,691 'drift':146 'drop':641 'e.g':42,354,538,599 'earn':299 'echo':78,100 'edit':231 'effect':669 'els':99 'english':511 'enough':590 'entri':82 'ephemer':777 'error':182 'eval':46 'everi':137,610 'everyth':171 'evid':787 'exact':135 'exist':543,580,705 'experi':386 'explain':518 'explor':346,370,380,631,767,791 'extract':415 'f':64 'fi':98,104 'file':55,66,73,496,699 'files/modules':498 'find':4 'first':361 'follow':377 'foobarhandl':567 'forbid':615 'frame':735 'friction':12,110,387,508,587 'full':153,274 'function':166,413 'futur':746,766 'fuzzi':708 'get':251,257 'give':329 'glossari':41,131,353,692 'good':332 'grill':633,644 'gt':87 'happen':670 'hard':449 'heurist':379 'hide':423 'high':209 'home':57 'home/.vibestack':58 'hypothet':310 'imagin':278 'implement':26,165,191,218,409 'improv':2,105,531 'improve-arch':1 'inform':319 'inlin':671 'insid':194 'intak':563 'interfac':24,162,170,199,207,212,222,244,303,403,455,619,793 'interface-design.md':799,800 'invari':181 'involv':500 'keep':301 'key':267 'know':175 'knowledg':262 'l':71 'languag':140,328 'language.md':156,157,270,271,548,549 'lazili':700 'leak':437 'learn':54,65,68,72,79,80,85,101 'leverag':196,210,248,524 'like':629 'limit':93 'list':275,489,609 'litig':343 'live':223 'load':83,729 'load-bear':728 'local':254,430,522 'loop':634 'lot':201 'maintain':256 'mani':396 'mark':596 'mode':183 'model':325 'modul':19,119,158,179,281,398,401,436,564,659,678,797 'move':473 'must':174 'n':295 'name':330,675 'navig':34,130 'near':213,404 'need':763 'none':102 'note':383 'number':488 'offer':732,756 'one':22,122,265,308,391,721,788 'opportun':6,114,492 'order':184,558,562,571 'organ':381 'packag':168 'part':442 'pass':289 'pass-through':288 'pick':638 'place':225,233,266 'plain':510 'point':143 'preambl':44 'present':484,486 'principl':268 'problem':501 'process':344 'project':37,322,349,534,687,719 'propos':14,112,618 'pure':412 're':342,427,752,771 're-litig':341 're-suggest':751,770 'read':359 'real':314,421,589 'reappear':293 'reason':731,759,778 'record':335,740 'refactor':15,115,612 'reject':723 'reopen':605 'requir':393 'review':748 'revisit':593 'right':715,782 'rigid':378 'satisfi':242 'say':557 'seam':219,247,311,315,333,440,664 'see':269,798 'self':786 'self-evid':785 'servic':149,572 'shallow':18,118,211,402,465 'shape':655 'sharpen':706 'side':668 'signal':480 'signatur':190 'sit':661 'skill':317,338 'skill-improve-arch' 'skip':776 'slice':169 'slug':52,60 'small':23,206,397 'solut':509 'source-timurgaleev' 'subag':368 'suggest':138,753,772 'surfac':10,108,307,583 'surviv':667 'suspect':463 'talk':559 'term':134,520,695,709 'test':277,306,451,459,529,666 'testabl':30,126,418 'theoret':611 'thing':241,775 'tight':434 'tightly-coupl':433 'tool':366 'topic-agent-skills' 'topic-ai-agents' 'topic-claude-code' 'topic-cursor-ide' 'topic-developer-tools' 'topic-kiro' 'topic-mcp' 'topic-prompt-engineering' 'topic-slash-commands' 'tr':76 'tree':649 'true':97 'turn':17,117 'two':312 'type':180,189,369 'understand':390 'unknown':53,61 'untest':447 'updat':713 'use':132,177,234,363,532,688,720 'user':623,637,722 'vanish':284 'vibestack':56 'vocabulari':537,550 'walk':372,646 'want':482,737,789 'warrant':592 'wc':70 'without':230 'worth':604,780 'would':466,515,530,627,760 'yes':476 'yet':103,620,683","prices":[{"id":"093187ff-1d91-484d-b545-178a0843a773","listingId":"964fb51f-b867-49c8-ae8d-f20fb950e82c","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"timurgaleev","category":"vibestack","install_from":"skills.sh"},"createdAt":"2026-05-18T19:06:21.547Z"}],"sources":[{"listingId":"964fb51f-b867-49c8-ae8d-f20fb950e82c","source":"github","sourceId":"timurgaleev/vibestack/improve-arch","sourceUrl":"https://github.com/timurgaleev/vibestack/tree/main/skills/improve-arch","isPrimary":false,"firstSeenAt":"2026-05-18T19:06:21.547Z","lastSeenAt":"2026-05-18T19:06:21.547Z"}],"details":{"listingId":"964fb51f-b867-49c8-ae8d-f20fb950e82c","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"timurgaleev","slug":"improve-arch","github":{"repo":"timurgaleev/vibestack","stars":15,"topics":["agent-skills","ai-agents","claude-code","cursor-ide","developer-tools","kiro","mcp","prompt-engineering","slash-commands"],"license":"mit","html_url":"https://github.com/timurgaleev/vibestack","pushed_at":"2026-05-18T18:19:05Z","description":"vibestack is a portable skill pack for AI coding agents. Slash commands like /office-hours, /ship, /investigate, /tdd, /review install once and work across every agent that supports the Agent Skills open standard — Claude Code, Cursor, Kiro, and a growing list of others. ","skill_md_sha":"f3d6992f477c5cd82df1f43bfd39c8ed17c5c30a","skill_md_path":"skills/improve-arch/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/timurgaleev/vibestack/tree/main/skills/improve-arch"},"layout":"multi","source":"github","category":"vibestack","frontmatter":{"name":"improve-arch","description":"Find deepening opportunities in a codebase. Surface architectural friction and\npropose refactors that turn shallow modules into deep ones — small interface,\ndeep implementation. The aim is testability and AI-navigability.\nIf your project has a domain glossary (e.g. `CONTEXT.md`) or ADRs (`docs/adr/`),\nthe skill uses them to keep names consistent and avoid re-litigating decisions.\nUse when asked to \"improve architecture\", \"find refactoring opportunities\",\n\"deepen modules\", \"consolidate tightly-coupled modules\", or to make a codebase\nmore testable and AI-navigable."},"skills_sh_url":"https://skills.sh/timurgaleev/vibestack/improve-arch"},"updatedAt":"2026-05-18T19:06:21.547Z"}}