@hyperdrive.bot/gut 0.1.15 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperdrive.bot/gut",
-  "version": "0.1.15",
+  "version": "0.2.0",
   "description": "Git Unified Tooling - Enhanced git with workspace intelligence for entity-based organization",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -93,4 +93,4 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   }
-}
+}

package/templates/claude-init/claude-md-section.md

@@ -0,0 +1,179 @@
+<!-- gut:start -->
+# Gut — Workspace Intelligence
+
+## What is Gut
+
+Gut is an entity-aware workspace manager for multi-repo and monorepo setups. It wraps git with workspace intelligence — focus-driven commands that scope operations to the entities you care about, dependency analysis across repos, and atomic multi-repo worktree isolation. The CLI is `gut` (npm: `@hyperdrive.bot/gut`).
+
+## Mental Model
+
+### Entities
+
+Entities are the building blocks of your workspace. Each entity has a type, name, and path:
+
+| Type | Purpose |
+|------|---------|
+| `client` | Client projects |
+| `company` | Company-level repositories |
+| `delivery` | Delivery/app projects |
+| `initiative` | Internal initiatives |
+| `module` | Packages and libraries |
+| `prospect` | Prospect/sales projects |
+| `service` | Backend services |
+| `system` | System-level infrastructure |
+| `tool` | Developer tools |
+
+Entities are stored in `.gut/config.json` and auto-discovered from directory patterns (`apps/` → delivery, `packages/` → module, `libs/` → module, `services/` → service, `tools/` → tool).
+
+### Focus System
+
+Focus scopes all gut commands to selected entities. When you focus on an entity, commands like `gut status`, `gut commit`, and `gut push` operate only on that entity's repository.
+
+| Mode | Purpose |
+|------|---------|
+| `audit` | Reviewing code quality and compliance |
+| `debug` | Investigating and fixing issues |
+| `delivery` | Building and shipping features |
+| `proposal` | Preparing proposals and estimates |
+| `research` | Exploring and prototyping |
+| `strategy` | Planning and architecture |
+
+Focus state is stored in `.gut/focus.json` with history in `.gut/history.json` (max 10 entries).
+
+### Worktrees
+
+Gut provides atomic multi-repo isolation via `gut worktree create`. This creates a super-repo worktree plus per-entity worktrees on a new branch, allowing isolated pipeline runs without affecting your working tree. Default location: `~/.local/share/gut/worktrees/<slug>`.
+
+## Command Reference
+
+### Setup
+
+| Command | Description |
+|---------|-------------|
+| `gut init` | Initialize a gut workspace |
+| `gut quick-setup` | Quick workspace setup wizard |
+
+### Entity
+
+| Command | Description |
+|---------|-------------|
+| `gut entity add` | Add entity to workspace |
+| `gut entity clone` | Clone entity repository |
+| `gut entity clone-all` | Clone all entities |
+| `gut entity list` | List entities |
+| `gut entity remove` | Remove entity |
+
+### Focus
+
+| Command | Description |
+|---------|-------------|
+| `gut focus` | Set focus on entities |
+| `gut unfocus` | Clear focus |
+| `gut back` | Return to previous focus/branch |
+| `gut context` | Show current focus context |
+| `gut contexts` | List saved focus contexts |
+
+### Git
+
+| Command | Description |
+|---------|-------------|
+| `gut status` | Show git status for focused entities |
+| `gut commit` | Commit changes across focused entities |
+| `gut push` | Push changes to remotes |
+| `gut pull` | Pull changes from remotes |
+| `gut checkout` | Checkout branches across entities |
+| `gut sync` | Sync across entities |
+
+### Worktree
+
+| Command | Description |
+|---------|-------------|
+| `gut worktree create` | Create mirrored worktrees for super-repo + focused entities |
+| `gut worktree list` | List worktrees |
+| `gut worktree remove` | Remove worktree |
+| `gut worktree status` | Show worktree status |
+
+### Analysis
+
+| Command | Description |
+|---------|-------------|
+| `gut affected` | Detect entities potentially affected by changes |
+| `gut deps` | Analyze dependencies |
+| `gut graph` | Visualize dependency graph |
+| `gut related` | Find related entities |
+| `gut used-by` | Show what uses an entity |
+| `gut stack` | Show dependency stack |
+| `gut patterns` | Analyze patterns across codebase |
+| `gut insights` | Show insights about entities |
+| `gut audit` | Run audits across entities |
+
+### Tickets
+
+| Command | Description |
+|---------|-------------|
+| `gut ticket focus` | Focus on a ticket |
+| `gut ticket get` | Get ticket details |
+| `gut ticket list` | List tickets |
+| `gut ticket sync` | Sync tickets |
+| `gut ticket update` | Update ticket |
+| `gut ticket config` | Configure ticket system |
+
+### Auth
+
+| Command | Description |
+|---------|-------------|
+| `gut auth login` | Authenticate |
+| `gut auth logout` | Logout |
+| `gut auth status` | Show auth status |
+
+### Other
+
+| Command | Description |
+|---------|-------------|
+| `gut repos` | List repositories |
+| `gut recent` | Show recent activity |
+| `gut add` | Add a git submodule or dependency |
+| `gut extract` | Extract code/modules |
+| `gut workspace` | Workspace management |
+
+## Common Workflows
+
+1. **Start a client project:**
+   ```
+   gut init
+   gut entity add my-client client ./path
+   gut focus client my-client --mode delivery
+   gut context
+   ```
+
+2. **Check blast radius before changes:**
+   ```
+   gut affected --verbose
+   ```
+   Review confidence levels (high/medium/low) and dependency reasons before making cross-entity changes.
+
+3. **Create isolated worktree for pipeline run:**
+   ```
+   gut focus client my-client
+   gut worktree create feature-x --install
+   cd ~/.local/share/gut/worktrees/feature-x
+   ```
+
+4. **Explore workspace:**
+   ```
+   gut entity list
+   gut focus <entity>
+   gut context
+   gut status --all --verbose
+   ```
+
+## Rules for Claude
+
+- Prefer `gut` commands over raw `git` when inside a gut workspace (`.gut/` directory exists)
+- Always check current focus with `gut context` before suggesting git operations
+- Use `gut affected --verbose` to understand blast radius before making cross-entity changes
+- Never modify `.gut/` directory contents directly — use gut commands
+- Use `gut status --all --verbose` for full workspace status, not `git status`
+- When a gut command fails, check if the workspace is initialized (`gut init`) and if entities are focused (`gut context`)
+- Use `gut worktree create` for isolated pipeline/workflow runs — never create git worktrees manually in a gut workspace
+<!-- gut:end -->

package/templates/claude-init/commands/gut-affected.md

@@ -0,0 +1,40 @@
+Analyze which entities are potentially affected by recent changes in the current focus.
+
+## Steps
+
+1. Run `gut affected --verbose` to detect entities affected by changes since the last commit
+
+## Fallback — no entities focused
+
+If the command fails or returns no results because no entities are currently focused:
+
+1. Tell the user: "No entities are focused. You need to focus on an entity first."
+2. Suggest: Run `gut focus <entity-name>` to set focus on the entity you're working on
+3. Then retry `/gut-affected`
+
+## Interpreting the output
+
+### Confidence levels
+Results are grouped by how likely an entity is to be affected:
+- **High** — direct dependency or shared code path changed
+- **Medium** — related configuration or schema change detected
+- **Low** — indirect or transitive dependency change
+
+### Change types
+Each affected entity shows what kind of change triggered the detection:
+- **API** — API contract or endpoint changes
+- **Config** — configuration file changes (serverless.yml, package.json, etc.)
+- **Schema** — database schema or type definition changes
+- **Dependency** — shared dependency or package version changes
+
+### Verbose output
+With `--verbose`, each affected entity includes a file-level breakdown showing exactly which changed files triggered the detection.
+
+## Suggested actions
+
+Based on the affected entities list, suggest which entities the user should:
+- **Review** — entities with high-confidence API or schema changes
+- **Test** — entities with config or dependency changes that may break at runtime
+- **Deploy** — entities that depend on the changed code and need redeployment
+
+Prioritize high-confidence results first. For low-confidence results, mention them but note they may not require immediate action.

package/templates/claude-init/commands/gut-status.md

@@ -0,0 +1,33 @@
+Show the current gut context and git status across all entities in the super-repo.
+
+## Steps
+
+1. Run `gut context` to show the current focus context (which entities are focused, their types, and paths)
+2. Run `gut status --all --verbose` to show git status across all entities with file-level detail
+
+## Interpreting the output
+
+### Entity type emojis
+- 🏢 = client
+- 🚀 = initiative
+- 🏗️ = company
+- 📦 = package
+- 🌐 = web-app
+
+### Status indicators
+- ✓ = clean (no uncommitted changes)
+- ● = has changes (staged, unstaged, or untracked files)
+
+### Verbose output
+When `--verbose` is used, each entity with changes shows file-level details:
+- **Staged** — files added to the index, ready to commit
+- **Unstaged** — modified files not yet staged
+- **Untracked** — new files not tracked by git
+
+## Summary
+
+After running both commands, present a concise summary of:
+- Which entities have uncommitted changes
+- What kind of changes each has (staged, unstaged, untracked)
+- How many files are affected per entity
+- Any entities that are currently focused