architecture-compass

Name: architecture-compass
Author: techygarg

165stars12forks

How to install architecture-compass?

techygarg/lattice/architecture-compass

$npx -y skills add techygarg/lattice --skill architecture-compass

Installs into the current project.

Summary

Architectural thinking partner for an existing repository — scans the codebase, conducts a structured interview, agrees on current architectural state and recommended direction, and produces a shareable insights document. Scoped to one repository, module, or folder. Does not exec

Files · 1

View on GitHub

SKILL.md

1	# Architecture Compass
2
3	## Required Skills
4
5	Read, apply:
6
7	1. `framework:knowledge-priming` -- Load codebase context: language, framework, structure, conventions (always)
8	2. `framework:architecture` -- Architectural audit lens and recommended direction guardrails (always)
9	3. `framework:domain-driven-design` -- Strategic DDD only: bounded contexts, domain seams (conditional: only when domain complexity warrants it)
10	4. `framework:collaborative-judgment` -- Surface judgment calls during co-design rounds (always)
11
12	## Workflow
13
14	### Step 1: Load Existing Context
15
16	Check for an existing insights document first. If `.lattice/insights/architecture.md` already exists:
17	- Read it. Check the Session Status table using these three states:
18	- `pending` — row exists, no content written yet
19	- `in-progress` — content exists in the section but no agreed date recorded
20	- `✅ agreed` — content exists and date is recorded
21	- Resume from the earliest `pending` or `in-progress` phase. For `in-progress` phases: present the existing content for re-confirmation rather than regenerating it.
22	- In-progress without content: If Current Architecture is `in-progress` but the document has no Current Architecture content (the previous session's scan context was lost), re-run Step 2 scan before presenting.
23	- Staleness check: If the most recent `✅ agreed` date in the Session Status table is older than 30 days, run a lightweight re-scan (Steps 2.1 and 2.6 only — tree + imports). If material structural changes are detected, present them and ask whether Current Architecture needs revision before proceeding.
24	- Do not re-scan if Current Architecture is already `✅ agreed` and the staleness check passes.
25	- Tell the user what was found and which phase the session resumes from.
26
27	If no existing document: proceed from Step 2.
28
29	Check for `.lattice/config.yaml`. Load `knowledge-base.md` and `architecture.md` from `.lattice/standards/` if they exist — these shape both the audit lens and the recommended direction proposal.
30
31	If no `.lattice/` config exists, offer to run `lattice-init` first. If declined, infer defaults from the scan.
32
33	---
34
35	### Step 2: Silent Scan — Architectural Signal Extraction
36
37	Do not ask any questions yet. Scan first, form a hypothesis, then ask only what code cannot reveal.
38
39	Confirm scope before scanning. If the working directory is a monorepo or contains multiple independent services/modules, ask: "Which service or module should this assessment focus on?" Do not scan the full monorepo root — assess one bounded scope at a time. If the user requests the full monorepo: explain that a single insights document cannot meaningfully capture many independent architectures. Offer: (1) assess the shared infrastructure/platform layer as one scope, (2) produce a lightweight index of all services with one-line architecture classification, then deep-assess the 2–3 most painful ones. If the user still insists, proceed with a service-by-service scan at reduced depth (Steps 2.1 + 2.6 per service).
40
41	This is signal extraction, not a full read. Target: 15–25 file reads (view/open operations). Grep, glob, and directory listings do not count against this budget — they are structural reconnaissance, not deep reads. Stop reading a module once its responsibility, dependencies, and layer fit are clear.
42
43	Scanning protocol — execute in order:
44
45	1. Directory tree (3 levels deep) — intended organization, layer structure, naming conventions. Do this before opening any file.
46
47	2. Dependency manifests — `package.json`, `pom.xml`, `go.mod`, `requirements.txt`. Language, framework, key external dependencies.
48
49	3. Architecture documents — `README.md`, `ARCHITECTURE.md`, `docs/`, ADR directories. The intended architecture often lives here — the gap between intention and reality is itself a finding.
50
51	4. Archaeology — before analysing flows, reduce scope:
52	- Dead code (no callers) — candidates for deletion, but verify no side effects first: static initializers, scheduled tasks, event listeners, and framework hooks are invisible to call-graph analysis
53	- Duplicate functionality — two implementations of the same concept, must reconcile before any change
54	- Implicit coupling — shared mutable state, globals, ambient context, thread-locals
55	- Hidden integration points — outbound calls to external systems in unexpected p

People who liked this also viewed

6 picks

Type

architecture-compass

165stars12forks

View on GitHub

How to install architecture-compass?

techygarg/lattice/architecture-compass

$npx -y skills add techygarg/lattice --skill architecture-compass

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Architecture Compass
2
3	## Required Skills
4
5	Read, apply:
6
7	1. `framework:knowledge-priming` -- Load codebase context: language, framework, structure, conventions (always)
8	2. `framework:architecture` -- Architectural audit lens and recommended direction guardrails (always)
9	3. `framework:domain-driven-design` -- Strategic DDD only: bounded contexts, domain seams (conditional: only when domain complexity warrants it)
10	4. `framework:collaborative-judgment` -- Surface judgment calls during co-design rounds (always)
11
12	## Workflow
13
14	### Step 1: Load Existing Context
15
16	Check for an existing insights document first. If `.lattice/insights/architecture.md` already exists:
17	- Read it. Check the Session Status table using these three states:
18	- `pending` — row exists, no content written yet
19	- `in-progress` — content exists in the section but no agreed date recorded
20	- `✅ agreed` — content exists and date is recorded
21	- Resume from the earliest `pending` or `in-progress` phase. For `in-progress` phases: present the existing content for re-confirmation rather than regenerating it.
22	- In-progress without content: If Current Architecture is `in-progress` but the document has no Current Architecture content (the previous session's scan context was lost), re-run Step 2 scan before presenting.
23	- Staleness check: If the most recent `✅ agreed` date in the Session Status table is older than 30 days, run a lightweight re-scan (Steps 2.1 and 2.6 only — tree + imports). If material structural changes are detected, present them and ask whether Current Architecture needs revision before proceeding.
24	- Do not re-scan if Current Architecture is already `✅ agreed` and the staleness check passes.
25	- Tell the user what was found and which phase the session resumes from.
26
27	If no existing document: proceed from Step 2.
28
29	Check for `.lattice/config.yaml`. Load `knowledge-base.md` and `architecture.md` from `.lattice/standards/` if they exist — these shape both the audit lens and the recommended direction proposal.
30
31	If no `.lattice/` config exists, offer to run `lattice-init` first. If declined, infer defaults from the scan.
32
33	---
34
35	### Step 2: Silent Scan — Architectural Signal Extraction
36
37	Do not ask any questions yet. Scan first, form a hypothesis, then ask only what code cannot reveal.
38
39	Confirm scope before scanning. If the working directory is a monorepo or contains multiple independent services/modules, ask: "Which service or module should this assessment focus on?" Do not scan the full monorepo root — assess one bounded scope at a time. If the user requests the full monorepo: explain that a single insights document cannot meaningfully capture many independent architectures. Offer: (1) assess the shared infrastructure/platform layer as one scope, (2) produce a lightweight index of all services with one-line architecture classification, then deep-assess the 2–3 most painful ones. If the user still insists, proceed with a service-by-service scan at reduced depth (Steps 2.1 + 2.6 per service).
40
41	This is signal extraction, not a full read. Target: 15–25 file reads (view/open operations). Grep, glob, and directory listings do not count against this budget — they are structural reconnaissance, not deep reads. Stop reading a module once its responsibility, dependencies, and layer fit are clear.
42
43	Scanning protocol — execute in order:
44
45	1. Directory tree (3 levels deep) — intended organization, layer structure, naming conventions. Do this before opening any file.
46
47	2. Dependency manifests — `package.json`, `pom.xml`, `go.mod`, `requirements.txt`. Language, framework, key external dependencies.
48
49	3. Architecture documents — `README.md`, `ARCHITECTURE.md`, `docs/`, ADR directories. The intended architecture often lives here — the gap between intention and reality is itself a finding.
50
51	4. Archaeology — before analysing flows, reduce scope:
52	- Dead code (no callers) — candidates for deletion, but verify no side effects first: static initializers, scheduled tasks, event listeners, and framework hooks are invisible to call-graph analysis
53	- Duplicate functionality — two implementations of the same concept, must reconcile before any change
54	- Implicit coupling — shared mutable state, globals, ambient context, thread-locals
55	- Hidden integration points — outbound calls to external systems in unexpected p

People who liked this also viewed

6 picks

Type