archrip 0.1.2

package/dist/templates/slash-commands/claude/archrip-scan.md

@@ -0,0 +1,140 @@
+---
+description: Scan codebase and generate architecture diagram data
+---
+
+# archrip scan — Analyze codebase architecture
+
+Analyze the current codebase and generate `.archrip/architecture.json`.
+
+**Language rule:** Respond in the same language as the user's message or `$ARGUMENTS`. If no user text is available, detect the project's primary language from README/docs and match it. The `architecture.json` fields (labels, descriptions) should also use that language.
+
+## Phase 1: Project Discovery
+1. Read top-level files (package.json, composer.json, go.mod, Cargo.toml, pom.xml, pyproject.toml, etc.)
+2. Identify language, framework, source root
+3. List directory structure (2 levels deep)
+4. Auto-detect `sourceUrl`: Run `git remote get-url origin` and convert to browse URL:
+   - `git@github.com:org/repo.git` → `https://github.com/org/repo/blob/main/{filePath}`
+   - `https://github.com/org/repo.git` → `https://github.com/org/repo/blob/main/{filePath}`
+   - `git@gitlab.com:org/repo.git` → `https://gitlab.com/org/repo/-/blob/main/{filePath}`
+   - If no git remote, leave empty (ask in Phase 7)
+
+## Phase 2: Documentation Discovery
+Read existing documentation to understand architecture context:
+1. Check for: README.md, CLAUDE.md, docs/, doc/, wiki/, ARCHITECTURE.md, CONTRIBUTING.md
+2. Extract: system overview, component descriptions, external service integrations, design decisions
+3. Use this knowledge to inform the analysis — documentation often reveals architectural intent that code alone does not show (use cases, business context, external dependencies)
+
+## Phase 3: Layer Identification
+Based on the framework, identify architectural layers:
+
+**Common patterns:**
+- Laravel: Controllers → Services → Ports → Adapters → Models
+- Express/NestJS: Routes/Controllers → Services → Repositories → Models
+- Next.js: Pages → Components → Hooks → API Routes → Services
+- Django: Views → Serializers → Services → Models
+- Spring Boot: Controllers → Services → Repositories → Entities
+- Go: Handlers → Services → Repositories → Models
+- Generic: Group by directory responsibility
+
+## Phase 4: Read Key Files
+For each layer, read representative files to extract:
+- Component names and purposes
+- Dependencies (imports, injections)
+- Public methods/routes
+- Database schemas (from migrations or model definitions)
+
+**Do NOT read every file.** Focus on entry points, core logic, interfaces, and data models.
+
+## Phase 5: Map Relationships
+For each component, identify:
+- What it depends on (imports, constructor injection)
+- What depends on it
+- External service connections
+
+**Connectivity check:** After mapping, verify every node has at least one edge. If a node is orphaned:
+- DTOs/entities → connect to the service or adapter that references them
+- External services → connect to the adapter/controller that integrates with them
+- Models → connect to the adapter/repository that queries them
+
+## Phase 6: Identify Use Cases
+Group related components into user-facing features.
+
+## Phase 7: Draft Review — STOP and ask the developer
+
+**IMPORTANT: Do NOT proceed to Phase 8 until the developer responds. You MUST stop here and wait for input.**
+
+Present a summary of what you found:
+- **Documents read**: List all docs you read in Phase 2 (e.g., README.md, CLAUDE.md, docs/architecture.md)
+- List of discovered nodes (grouped by layer/category)
+- List of discovered use cases
+- External services found
+
+Then ask:
+- Are there other documents you should read? (e.g., docs/, wiki/, design docs)
+- Are there missing components, external services, or use cases?
+- Should anything be excluded?
+- `sourceUrl` auto-detected as: `<detected-url>` — correct? (If not detected, ask for the `sourceUrl` template, e.g., `https://github.com/org/repo/blob/main/{filePath}`)
+
+End your message with: **"Please review and reply with corrections, or type 'go' to generate."**
+
+**Do NOT write architecture.json yet. Wait for the developer to respond.**
+
+If the developer replies with corrections, apply them and present the updated summary. Repeat until they say "go" / "ok" / "skip".
+
+## Phase 8: Generate architecture.json
+Only run this phase AFTER the developer has approved the draft in Phase 7.
+
+Create `.archrip/` directory if it doesn't exist, then write the complete `.archrip/architecture.json` following the schema, incorporating developer feedback.
+
+After writing the file:
+1. Run `npx archrip serve` in the terminal (auto-builds if needed, opens browser)
+2. Tell the developer: Run `/archrip-update` to make further adjustments (add/remove nodes, fix relationships, etc.)
+
+### Required structure (use EXACTLY these field names)
+
+```json
+{
+  "version": "1.0",
+  "project": { "name": "...", "sourceUrl": "https://github.com/org/repo/blob/main/{filePath}" },
+  "nodes": [
+    { "id": "ctrl-users", "category": "controller", "label": "UsersController", "layer": 1, "filePath": "src/controllers/users.ts", "useCases": ["uc-user-mgmt"] }
+  ],
+  "edges": [
+    { "source": "ctrl-users", "target": "svc-users", "type": "dependency" }
+  ],
+  "useCases": [
+    { "id": "uc-user-mgmt", "name": "User Management", "nodeIds": ["ctrl-users", "svc-users"] }
+  ]
+}
+```
+
+**Critical field names — do NOT use alternatives:**
+- Node: `id`, `category`, `label` (NOT name), `layer` — all required
+- Edge: `source`, `target` (NOT from/to) — all required
+- UseCase: `id`, `name`, `nodeIds` — all required
+
+### Node Rules
+- `id`: kebab-case, prefixed by category abbreviation (ctrl-, svc-, port-, adpt-, model-, ext-, job-, dto-)
+- `layer`: 0=external, 1=entry points, 2=application logic, 3=abstractions, 4=implementations, 5=data
+- `category`: one of controller, service, port, adapter, model, external, job, dto (or custom)
+- `label`: display name for the node
+- `filePath`: relative from project root
+- `depth` (optional): 0=overview (boundary), 1=structure (internal), 2=detail (implementation). Auto-inferred from category if omitted
+- `useCases`: array of use case IDs this node participates in
+
+### Edge Rules
+- `source`: source node id
+- `target`: target node id
+- `type`: dependency | implements | relation
+- Only include significant architectural dependencies (not utility imports)
+- **Every node MUST have at least one edge.** If a node has no obvious dependency, connect it with a `relation` edge to the component that uses or contains it.
+
+### Layout Selection
+- DDD / Clean Architecture / Hexagonal / Onion Architecture → add `"layout": "concentric"` to `project`
+- MVC / standard layered → `"layout": "dagre"` (default, can be omitted)
+
+### Schema Rules
+- Include table schema only when migration files or model annotations are available
+- Reference from node data using schema key name
+
+$ARGUMENTS

package/dist/templates/slash-commands/claude/archrip-update.md

@@ -0,0 +1,34 @@
+---
+description: Update or refine the architecture diagram
+---
+
+# archrip update — Update architecture diagram
+
+Read `.archrip/architecture.json` and update it.
+
+## Mode 1: Auto-detect from git diff (no arguments)
+
+If `$ARGUMENTS` is empty:
+
+1. Run `git diff --name-only HEAD~10` to find changed files
+2. Read the current `.archrip/architecture.json`
+3. For each changed file:
+   - New component? → Add node + edges
+   - Removed component? → Remove node + edges + use case references
+   - Changed dependencies? → Update edges
+4. Preserve existing node IDs for unchanged components
+5. Write updated `.archrip/architecture.json`
+
+## Mode 2: Apply requested changes (with arguments)
+
+If `$ARGUMENTS` is provided, apply the user's requested changes:
+- Add/remove/modify nodes
+- Fix relationships
+- Add/modify use cases
+- Adjust layer assignments
+- Add database schemas
+- Improve descriptions
+
+Write the updated `.archrip/architecture.json`.
+
+$ARGUMENTS

package/dist/templates/slash-commands/claude/archrips-refine.md

@@ -0,0 +1,17 @@
+---
+description: Interactively refine the architecture diagram
+---
+
+# archrips refine — Refine architecture diagram
+
+Read `.archrips/architecture.json` and apply the user's requested changes:
+- Add/remove/modify nodes
+- Fix relationships
+- Add/modify use cases
+- Adjust layer assignments
+- Add database schemas
+- Improve descriptions
+
+Write the updated `.archrips/architecture.json`.
+
+$ARGUMENTS

package/dist/templates/slash-commands/claude/archrips-scan.md

@@ -0,0 +1,97 @@
+---
+description: Scan codebase and generate architecture diagram data
+---
+
+# archrips scan — Analyze codebase architecture
+
+Analyze the current codebase and generate `.archrips/architecture.json`.
+
+**Language rule:** Respond in the same language as the user's message or `$ARGUMENTS`. If no user text is available, detect the project's primary language from README/docs and match it. The `architecture.json` fields (labels, descriptions) should also use that language.
+
+## Phase 1: Project Discovery
+1. Read top-level files (package.json, composer.json, go.mod, Cargo.toml, pom.xml, pyproject.toml, etc.)
+2. Identify language, framework, source root
+3. List directory structure (2 levels deep)
+
+## Phase 2: Documentation Discovery
+Read existing documentation to understand architecture context:
+1. Check for: README.md, CLAUDE.md, docs/, doc/, wiki/, ARCHITECTURE.md, CONTRIBUTING.md
+2. Extract: system overview, component descriptions, external service integrations, design decisions
+3. Use this knowledge to inform the analysis — documentation often reveals architectural intent that code alone does not show (use cases, business context, external dependencies)
+
+## Phase 3: Layer Identification
+Based on the framework, identify architectural layers:
+
+**Common patterns:**
+- Laravel: Controllers → Services → Ports → Adapters → Models
+- Express/NestJS: Routes/Controllers → Services → Repositories → Models
+- Next.js: Pages → Components → Hooks → API Routes → Services
+- Django: Views → Serializers → Services → Models
+- Spring Boot: Controllers → Services → Repositories → Entities
+- Go: Handlers → Services → Repositories → Models
+- Generic: Group by directory responsibility
+
+## Phase 4: Read Key Files
+For each layer, read representative files to extract:
+- Component names and purposes
+- Dependencies (imports, injections)
+- Public methods/routes
+- Database schemas (from migrations or model definitions)
+
+**Do NOT read every file.** Focus on entry points, core logic, interfaces, and data models.
+
+## Phase 5: Map Relationships
+For each component, identify:
+- What it depends on (imports, constructor injection)
+- What depends on it
+- External service connections
+
+## Phase 6: Identify Use Cases
+Group related components into user-facing features.
+
+## Phase 7: Draft Review — STOP and ask the developer
+
+**IMPORTANT: Do NOT proceed to Phase 8 until the developer responds. You MUST stop here and wait for input.**
+
+Present a summary of what you found:
+- List of discovered nodes (grouped by layer/category)
+- List of discovered use cases
+- External services found
+
+Then ask:
+- Are there missing components, external services, or use cases?
+- Should anything be excluded?
+- What is the `sourceUrl` template? (e.g., `https://github.com/org/repo/blob/main/{filePath}`)
+
+End your message with: **"Please review and reply with corrections, or type 'go' to generate."**
+
+**Do NOT write architecture.json yet. Wait for the developer to respond.**
+
+If the developer replies with corrections, apply them and present the updated summary. Repeat until they say "go" / "ok" / "skip".
+
+## Phase 8: Generate architecture.json
+Only run this phase AFTER the developer has approved the draft in Phase 7.
+
+Write the complete `.archrips/architecture.json` following the schema, incorporating developer feedback.
+
+After writing the file, tell the developer:
+- Run `npx archrips build && npx archrips serve` to preview
+- Run `/archrips-refine` to make further adjustments (add/remove nodes, fix relationships, etc.)
+
+### Node Rules
+- `id`: kebab-case, prefixed by category abbreviation (ctrl-, svc-, port-, adpt-, model-, ext-, job-, dto-)
+- `layer`: 0=external, 1=entry points, 2=application logic, 3=abstractions, 4=implementations, 5=data
+- `category`: one of controller, service, port, adapter, model, external, job, dto (or custom)
+- `filePath`: relative from project root
+- `depth` (optional): 0=overview (boundary), 1=structure (internal), 2=detail (implementation). Auto-inferred from category if omitted
+- `useCases`: array of use case IDs this node participates in
+
+### Edge Rules
+- `type`: dependency | implements | relation
+- Only include significant architectural dependencies (not utility imports)
+
+### Schema Rules
+- Include table schema only when migration files or model annotations are available
+- Reference from node data using schema key name
+
+$ARGUMENTS

package/dist/templates/slash-commands/claude/archrips-update.md

@@ -0,0 +1,18 @@
+---
+description: Update architecture diagram after code changes
+---
+
+# archrips update — Incremental architecture update
+
+Update `.archrips/architecture.json` based on recent code changes.
+
+1. Run `git diff --name-only HEAD~10` to find changed files
+2. Read the current `.archrips/architecture.json`
+3. For each changed file:
+   - New component? → Add node + edges
+   - Removed component? → Remove node + edges + use case references
+   - Changed dependencies? → Update edges
+4. Preserve existing node IDs for unchanged components
+5. Write updated `.archrips/architecture.json`
+
+$ARGUMENTS

package/dist/templates/slash-commands/codex/archrip-refine.md

@@ -0,0 +1,17 @@
+---
+description: Interactively refine the architecture diagram
+---
+
+# archrip refine — Refine architecture diagram
+
+Read `.archrip/architecture.json` and apply the user's requested changes:
+- Add/remove/modify nodes
+- Fix relationships
+- Add/modify use cases
+- Adjust layer assignments
+- Add database schemas
+- Improve descriptions
+
+Write the updated `.archrip/architecture.json`.
+
+$ARGUMENTS

package/dist/templates/slash-commands/codex/archrip-scan.md

@@ -0,0 +1,140 @@
+---
+description: Scan codebase and generate architecture diagram data
+---
+
+# archrip scan — Analyze codebase architecture
+
+Analyze the current codebase and generate `.archrip/architecture.json`.
+
+**Language rule:** Respond in the same language as the user's message or `$ARGUMENTS`. If no user text is available, detect the project's primary language from README/docs and match it. The `architecture.json` fields (labels, descriptions) should also use that language.
+
+## Phase 1: Project Discovery
+1. Read top-level files (package.json, composer.json, go.mod, Cargo.toml, pom.xml, pyproject.toml, etc.)
+2. Identify language, framework, source root
+3. List directory structure (2 levels deep)
+4. Auto-detect `sourceUrl`: Run `git remote get-url origin` and convert to browse URL:
+   - `git@github.com:org/repo.git` → `https://github.com/org/repo/blob/main/{filePath}`
+   - `https://github.com/org/repo.git` → `https://github.com/org/repo/blob/main/{filePath}`
+   - `git@gitlab.com:org/repo.git` → `https://gitlab.com/org/repo/-/blob/main/{filePath}`
+   - If no git remote, leave empty (ask in Phase 7)
+
+## Phase 2: Documentation Discovery
+Read existing documentation to understand architecture context:
+1. Check for: README.md, CLAUDE.md, docs/, doc/, wiki/, ARCHITECTURE.md, CONTRIBUTING.md
+2. Extract: system overview, component descriptions, external service integrations, design decisions
+3. Use this knowledge to inform the analysis — documentation often reveals architectural intent that code alone does not show (use cases, business context, external dependencies)
+
+## Phase 3: Layer Identification
+Based on the framework, identify architectural layers:
+
+**Common patterns:**
+- Laravel: Controllers → Services → Ports → Adapters → Models
+- Express/NestJS: Routes/Controllers → Services → Repositories → Models
+- Next.js: Pages → Components → Hooks → API Routes → Services
+- Django: Views → Serializers → Services → Models
+- Spring Boot: Controllers → Services → Repositories → Entities
+- Go: Handlers → Services → Repositories → Models
+- Generic: Group by directory responsibility
+
+## Phase 4: Read Key Files
+For each layer, read representative files to extract:
+- Component names and purposes
+- Dependencies (imports, injections)
+- Public methods/routes
+- Database schemas (from migrations or model definitions)
+
+**Do NOT read every file.** Focus on entry points, core logic, interfaces, and data models.
+
+## Phase 5: Map Relationships
+For each component, identify:
+- What it depends on (imports, constructor injection)
+- What depends on it
+- External service connections
+
+**Connectivity check:** After mapping, verify every node has at least one edge. If a node is orphaned:
+- DTOs/entities → connect to the service or adapter that references them
+- External services → connect to the adapter/controller that integrates with them
+- Models → connect to the adapter/repository that queries them
+
+## Phase 6: Identify Use Cases
+Group related components into user-facing features.
+
+## Phase 7: Draft Review — STOP and ask the developer
+
+**IMPORTANT: Do NOT proceed to Phase 8 until the developer responds. You MUST stop here and wait for input.**
+
+Present a summary of what you found:
+- **Documents read**: List all docs you read in Phase 2 (e.g., README.md, CLAUDE.md, docs/architecture.md)
+- List of discovered nodes (grouped by layer/category)
+- List of discovered use cases
+- External services found
+
+Then ask:
+- Are there other documents you should read? (e.g., docs/, wiki/, design docs)
+- Are there missing components, external services, or use cases?
+- Should anything be excluded?
+- `sourceUrl` auto-detected as: `<detected-url>` — correct? (If not detected, ask for the `sourceUrl` template, e.g., `https://github.com/org/repo/blob/main/{filePath}`)
+
+End your message with: **"Please review and reply with corrections, or type 'go' to generate."**
+
+**Do NOT write architecture.json yet. Wait for the developer to respond.**
+
+If the developer replies with corrections, apply them and present the updated summary. Repeat until they say "go" / "ok" / "skip".
+
+## Phase 8: Generate architecture.json
+Only run this phase AFTER the developer has approved the draft in Phase 7.
+
+Create `.archrip/` directory if it doesn't exist, then write the complete `.archrip/architecture.json` following the schema, incorporating developer feedback.
+
+After writing the file:
+1. Run `npx archrip serve` in the terminal (auto-builds if needed, opens browser)
+2. Tell the developer: Run `/archrip-update` to make further adjustments (add/remove nodes, fix relationships, etc.)
+
+### Required structure (use EXACTLY these field names)
+
+```json
+{
+  "version": "1.0",
+  "project": { "name": "...", "sourceUrl": "https://github.com/org/repo/blob/main/{filePath}" },
+  "nodes": [
+    { "id": "ctrl-users", "category": "controller", "label": "UsersController", "layer": 1, "filePath": "src/controllers/users.ts", "useCases": ["uc-user-mgmt"] }
+  ],
+  "edges": [
+    { "source": "ctrl-users", "target": "svc-users", "type": "dependency" }
+  ],
+  "useCases": [
+    { "id": "uc-user-mgmt", "name": "User Management", "nodeIds": ["ctrl-users", "svc-users"] }
+  ]
+}
+```
+
+**Critical field names — do NOT use alternatives:**
+- Node: `id`, `category`, `label` (NOT name), `layer` — all required
+- Edge: `source`, `target` (NOT from/to) — all required
+- UseCase: `id`, `name`, `nodeIds` — all required
+
+### Node Rules
+- `id`: kebab-case, prefixed by category abbreviation (ctrl-, svc-, port-, adpt-, model-, ext-, job-, dto-)
+- `layer`: 0=external, 1=entry points, 2=application logic, 3=abstractions, 4=implementations, 5=data
+- `category`: one of controller, service, port, adapter, model, external, job, dto (or custom)
+- `label`: display name for the node
+- `filePath`: relative from project root
+- `depth` (optional): 0=overview (boundary), 1=structure (internal), 2=detail (implementation). Auto-inferred from category if omitted
+- `useCases`: array of use case IDs this node participates in
+
+### Edge Rules
+- `source`: source node id
+- `target`: target node id
+- `type`: dependency | implements | relation
+- Only include significant architectural dependencies (not utility imports)
+- **Every node MUST have at least one edge.** If a node has no obvious dependency, connect it with a `relation` edge to the component that uses or contains it.
+
+### Layout Selection
+- DDD / Clean Architecture / Hexagonal / Onion Architecture → add `"layout": "concentric"` to `project`
+- MVC / standard layered → `"layout": "dagre"` (default, can be omitted)
+
+### Schema Rules
+- Include table schema only when migration files or model annotations are available
+- Reference from node data using schema key name
+
+$ARGUMENTS

package/dist/templates/slash-commands/codex/archrip-update.md

@@ -0,0 +1,34 @@
+---
+description: Update or refine the architecture diagram
+---
+
+# archrip update — Update architecture diagram
+
+Read `.archrip/architecture.json` and update it.
+
+## Mode 1: Auto-detect from git diff (no arguments)
+
+If `$ARGUMENTS` is empty:
+
+1. Run `git diff --name-only HEAD~10` to find changed files
+2. Read the current `.archrip/architecture.json`
+3. For each changed file:
+   - New component? → Add node + edges
+   - Removed component? → Remove node + edges + use case references
+   - Changed dependencies? → Update edges
+4. Preserve existing node IDs for unchanged components
+5. Write updated `.archrip/architecture.json`
+
+## Mode 2: Apply requested changes (with arguments)
+
+If `$ARGUMENTS` is provided, apply the user's requested changes:
+- Add/remove/modify nodes
+- Fix relationships
+- Add/modify use cases
+- Adjust layer assignments
+- Add database schemas
+- Improve descriptions
+
+Write the updated `.archrip/architecture.json`.
+
+$ARGUMENTS

package/dist/templates/slash-commands/codex/archrips-refine.md

@@ -0,0 +1,17 @@
+---
+description: Interactively refine the architecture diagram
+---
+
+# archrips refine — Refine architecture diagram
+
+Read `.archrips/architecture.json` and apply the user's requested changes:
+- Add/remove/modify nodes
+- Fix relationships
+- Add/modify use cases
+- Adjust layer assignments
+- Add database schemas
+- Improve descriptions
+
+Write the updated `.archrips/architecture.json`.
+
+$ARGUMENTS

package/dist/templates/slash-commands/codex/archrips-scan.md

@@ -0,0 +1,97 @@
+---
+description: Scan codebase and generate architecture diagram data
+---
+
+# archrips scan — Analyze codebase architecture
+
+Analyze the current codebase and generate `.archrips/architecture.json`.
+
+**Language rule:** Respond in the same language as the user's message or `$ARGUMENTS`. If no user text is available, detect the project's primary language from README/docs and match it. The `architecture.json` fields (labels, descriptions) should also use that language.
+
+## Phase 1: Project Discovery
+1. Read top-level files (package.json, composer.json, go.mod, Cargo.toml, pom.xml, pyproject.toml, etc.)
+2. Identify language, framework, source root
+3. List directory structure (2 levels deep)
+
+## Phase 2: Documentation Discovery
+Read existing documentation to understand architecture context:
+1. Check for: README.md, CLAUDE.md, docs/, doc/, wiki/, ARCHITECTURE.md, CONTRIBUTING.md
+2. Extract: system overview, component descriptions, external service integrations, design decisions
+3. Use this knowledge to inform the analysis — documentation often reveals architectural intent that code alone does not show (use cases, business context, external dependencies)
+
+## Phase 3: Layer Identification
+Based on the framework, identify architectural layers:
+
+**Common patterns:**
+- Laravel: Controllers → Services → Ports → Adapters → Models
+- Express/NestJS: Routes/Controllers → Services → Repositories → Models
+- Next.js: Pages → Components → Hooks → API Routes → Services
+- Django: Views → Serializers → Services → Models
+- Spring Boot: Controllers → Services → Repositories → Entities
+- Go: Handlers → Services → Repositories → Models
+- Generic: Group by directory responsibility
+
+## Phase 4: Read Key Files
+For each layer, read representative files to extract:
+- Component names and purposes
+- Dependencies (imports, injections)
+- Public methods/routes
+- Database schemas (from migrations or model definitions)
+
+**Do NOT read every file.** Focus on entry points, core logic, interfaces, and data models.
+
+## Phase 5: Map Relationships
+For each component, identify:
+- What it depends on (imports, constructor injection)
+- What depends on it
+- External service connections
+
+## Phase 6: Identify Use Cases
+Group related components into user-facing features.
+
+## Phase 7: Draft Review — STOP and ask the developer
+
+**IMPORTANT: Do NOT proceed to Phase 8 until the developer responds. You MUST stop here and wait for input.**
+
+Present a summary of what you found:
+- List of discovered nodes (grouped by layer/category)
+- List of discovered use cases
+- External services found
+
+Then ask:
+- Are there missing components, external services, or use cases?
+- Should anything be excluded?
+- What is the `sourceUrl` template? (e.g., `https://github.com/org/repo/blob/main/{filePath}`)
+
+End your message with: **"Please review and reply with corrections, or type 'go' to generate."**
+
+**Do NOT write architecture.json yet. Wait for the developer to respond.**
+
+If the developer replies with corrections, apply them and present the updated summary. Repeat until they say "go" / "ok" / "skip".
+
+## Phase 8: Generate architecture.json
+Only run this phase AFTER the developer has approved the draft in Phase 7.
+
+Write the complete `.archrips/architecture.json` following the schema, incorporating developer feedback.
+
+After writing the file, tell the developer:
+- Run `npx archrips build && npx archrips serve` to preview
+- Run `/archrips-refine` to make further adjustments (add/remove nodes, fix relationships, etc.)
+
+### Node Rules
+- `id`: kebab-case, prefixed by category abbreviation (ctrl-, svc-, port-, adpt-, model-, ext-, job-, dto-)
+- `layer`: 0=external, 1=entry points, 2=application logic, 3=abstractions, 4=implementations, 5=data
+- `category`: one of controller, service, port, adapter, model, external, job, dto (or custom)
+- `filePath`: relative from project root
+- `depth` (optional): 0=overview (boundary), 1=structure (internal), 2=detail (implementation). Auto-inferred from category if omitted
+- `useCases`: array of use case IDs this node participates in
+
+### Edge Rules
+- `type`: dependency | implements | relation
+- Only include significant architectural dependencies (not utility imports)
+
+### Schema Rules
+- Include table schema only when migration files or model annotations are available
+- Reference from node data using schema key name
+
+$ARGUMENTS

package/dist/templates/slash-commands/codex/archrips-update.md

@@ -0,0 +1,18 @@
+---
+description: Update architecture diagram after code changes
+---
+
+# archrips update — Incremental architecture update
+
+Update `.archrips/architecture.json` based on recent code changes.
+
+1. Run `git diff --name-only HEAD~10` to find changed files
+2. Read the current `.archrips/architecture.json`
+3. For each changed file:
+   - New component? → Add node + edges
+   - Removed component? → Remove node + edges + use case references
+   - Changed dependencies? → Update edges
+4. Preserve existing node IDs for unchanged components
+5. Write updated `.archrips/architecture.json`
+
+$ARGUMENTS

package/dist/templates/slash-commands/gemini/archrip-refine.md

@@ -0,0 +1,17 @@
+---
+description: Interactively refine the architecture diagram
+---
+
+# archrip refine — Refine architecture diagram
+
+Read `.archrip/architecture.json` and apply the user's requested changes:
+- Add/remove/modify nodes
+- Fix relationships
+- Add/modify use cases
+- Adjust layer assignments
+- Add database schemas
+- Improve descriptions
+
+Write the updated `.archrip/architecture.json`.
+
+$ARGUMENTS