all-hands-cli 0.1.0

package/.allhands/workflows/triage.md

@@ -0,0 +1,81 @@
+---
+name: triage
+type: triage
+planning_depth: focused
+jury_required: false
+max_tangential_hypotheses: 1
+required_ideation_questions:
+  - "Describe the external signals"
+  - "What's the impact and urgency?"
+  - "What outcome do you need?"
+---
+
+## Domain Knowledge
+
+### External Signal Vocabulary
+
+Triage specs are driven by external signals that demand attention. Signal types to surface and categorize:
+
+| Signal Type | Examples |
+|-------------|----------|
+| **Error reports** | Stack traces, crash reports, error rate spikes |
+| **Analytics anomalies** | Conversion drops, usage pattern shifts, funnel breakdowns |
+| **Support tickets** | User complaints, feature requests, confusion patterns |
+| **Alerts** | Monitoring alerts, SLA breaches, resource exhaustion warnings |
+
+> **Note**: Full external source integration (PostHog, Sentry, PagerDuty) is deferred. This domain uses manually provided signal data.
+
+### Impact/Urgency Framework
+
+Triage prioritization is grounded in impact and urgency dimensions:
+
+| Dimension | Factors |
+|-----------|---------|
+| **Users affected** | Single user, subset, all users, public-facing |
+| **Revenue impact** | Direct revenue loss, conversion impact, churn risk |
+| **SLA risk** | Uptime commitments, response time guarantees, contractual obligations |
+| **Escalation trajectory** | Getting worse, stable, intermittent |
+
+### Outcome Taxonomy
+
+Triage outcomes range from diagnosis to action:
+
+| Outcome | Description |
+|---------|-------------|
+| **Root cause identification** | Diagnose the issue, document findings |
+| **Hotfix** | Ship a targeted fix for the immediate problem |
+| **Incident report** | Document what happened, impact, and prevention |
+| **Escalation** | Route to appropriate team or priority queue |
+
+## Ideation Guidance
+
+Per **Context is Precious**, triage needs external data to ground decisions in reality. The interview captures signal data that would otherwise require tool integration.
+
+### Probe Guidance
+
+- Probe vague signal descriptions — demand specific error messages, metrics, or user reports
+- Distinguish urgency from importance — time-sensitive vs high-impact may require different approaches
+
+### Output Sections
+
+Spec body sections for triage domain:
+- **Motivation**: External signals and their impact
+- **Goals**: Desired triage outcome
+- **Technical Considerations**: Manually provided signal data
+
+## Planning Considerations
+
+### External Signal Integration (Deferred)
+
+Full integration with external signal sources (PostHog, Sentry, PagerDuty) is deferred to a future spec. Current planning relies on engineer-provided signal data.
+
+### Urgency-Driven Prioritization
+
+Triage planning should be urgency-aware:
+- High urgency signals may require immediate hotfix prompts before diagnosis
+- Lower urgency allows for thorough investigation-style planning
+- Escalation trajectory informs whether the triage can be methodical or must be rapid
+
+### Prompt Output Range
+
+Triage specs produce 1-3 focused prompts. Triage is inherently rapid — minimal prompts with clear outcomes.

package/.claude/README.md

@@ -0,0 +1 @@
+These claude agents are included in order to prevent the default claude agents from being used, prefering these to be run that tightly align with the harness flows.

package/.claude/agents/explorer.md

@@ -0,0 +1,10 @@
+---
+name: explorer
+description: Must use for codebase exploration tasks. Fast, read-only codebase exploration agent. Use for file discovery, code search, understanding implementations, finding patterns, and gathering context. MUST USE INSTEAD OF THE DEFAULT CLAUDE EXPLORER AGENT.
+tools: Read, Glob, Grep, Bash, LSP
+model: opus
+color: green
+---
+
+You MUST follow the rules in:
+@.allhands/flows/shared/CODEBASE_UNDERSTANDING.md

package/.claude/agents/researcher.md

@@ -0,0 +1,11 @@
+---
+name: researcher
+description: |
+  External research specialist with web search capability. Use for ANY external information gathering: API docs, library documentation, best practices, implementation patterns, external URLs. Cannot implement - discovery only.
+tools: Read, Glob, Grep, Bash
+model: opus
+color: blue
+---
+
+You MUST follow the rules in:
+@.allhands/flows/shared/RESEARCH_GUIDANCE.md

package/.claude/agents/task-runner.md

@@ -0,0 +1,8 @@
+---
+name: task-runner
+description: Must use when spawning a sub-task requiring a read to a flow md file. 
+model: opus
+color: yellow
+---
+
+Read and follow the instructions in the flow md file provided. Output concisely and to the point, ensuring to include everything requested of you.

package/.claude/settings.json

@@ -0,0 +1,231 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "ah hooks observability session-start"
+          },
+          {
+            "type": "command",
+            "command": "ah hooks session tldr-warm"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "ah hooks observability prompt-submit"
+          },
+          {
+            "type": "command",
+            "command": "ah hooks context impact-refactor",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "(Task|Bash|Write|Edit|AskUserQuestion|EnterPlanMode|ExitPlanMode|LSP)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "ah hooks observability tool-pre"
+          }
+        ]
+      },
+      {
+        "matcher": "Grep",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "ah hooks context search-router"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "ah hooks context signature"
+          }
+        ]
+      },
+      {
+        "matcher": "(WebFetch|Bash)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "ah hooks enforcement github-url"
+          }
+        ]
+      },
+      {
+        "matcher": "WebFetch",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "ah hooks enforcement research-fetch"
+          }
+        ]
+      },
+      {
+        "matcher": "WebSearch",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "ah hooks enforcement research-search"
+          }
+        ]
+      },
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "ah hooks context tldr-inject"
+          },
+          {
+            "type": "command",
+            "command": "ah hooks context arch-inject"
+          }
+        ]
+      },
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "ah hooks context read-enforcer",
+            "timeout": 20
+          }
+        ]
+      },
+      {
+        "matcher": "(Write|Edit)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "ah hooks validation schema-pre"
+          }
+        ]
+      },
+      {
+        "matcher": "TaskOutput",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "ah hooks context transcript-safeguard-pre",
+            "timeout": 90
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "(Task|Bash|Write|Edit)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "ah hooks observability tool-post"
+          }
+        ]
+      },
+      {
+        "matcher": "(Write|Edit)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "ah hooks validation diagnostics"
+          },
+          {
+            "type": "command",
+            "command": "ah hooks validation format"
+          },
+          {
+            "type": "command",
+            "command": "ah hooks context edit-notify"
+          }
+        ]
+      }
+    ],
+    "PostToolUseFailure": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "ah hooks observability tool-failure"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "ah hooks observability agent-stop"
+          },
+          {
+            "type": "command",
+            "command": "DISABLE_DAEMON=true ah hooks lifecycle agent-stop"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "DISABLE_DAEMON=true ah hooks lifecycle agent-stop"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "ah hooks observability agent-compact"
+          },
+          {
+            "type": "command",
+            "command": "DISABLE_DAEMON=true ah hooks lifecycle agent-compact"
+          }
+        ]
+      }
+    ]
+  },
+  "env": {
+    "ENABLE_LSP_TOOL": "1"
+  },
+  "permissions": {
+    "deny": [
+      "Task(claude-code-guide)",
+      "Task(Plan)",
+      "Task(Explore)"
+    ],
+    "ask": []
+  },
+  "enableAllProjectMcpServers": false,
+  "enabledPlugins": {
+    "typescript-lsp@claude-plugins-official": true,
+    "pyright-lsp@claude-plugins-official": true,
+    "swift-lsp@claude-plugins-official": true
+  }
+}

package/.env.ai.example

@@ -0,0 +1,7 @@
+# claude-envoy API keys
+PERPLEXITY_API_KEY=
+TAVILY_API_KEY=
+GEMINI_API_KEY=
+XAI_API_KEY=
+CONTEXT7_API_KEY=
+OPENAI_API_KEY=

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,69 @@
+name: Publish Package
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  id-token: write  # Required for OIDC
+  contents: write  # Required for pushing version bump
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Update npm
+        run: npm install -g npm@latest
+
+      - run: npm ci
+
+      - name: Ensure version is higher than published
+        run: |
+          CURRENT=$(node -p "require('./package.json').version")
+          LATEST=$(npm view all-hands version 2>/dev/null || echo "0.0.0")
+
+          # Compare versions using node
+          NEEDS_BUMP=$(node -e "
+            const current = '$CURRENT'.split('.').map(Number);
+            const latest = '$LATEST'.split('.').map(Number);
+            const needsBump = current[0] < latest[0] ||
+              (current[0] === latest[0] && current[1] < latest[1]) ||
+              (current[0] === latest[0] && current[1] === latest[1] && current[2] <= latest[2]);
+            console.log(needsBump ? 'true' : 'false');
+          ")
+
+          if [ "$NEEDS_BUMP" = "true" ]; then
+            echo "Local $CURRENT <= published $LATEST, bumping to patch above $LATEST..."
+            npm version $LATEST --no-git-tag-version --allow-same-version
+            npm version patch --no-git-tag-version
+            echo "BUMPED=true" >> $GITHUB_ENV
+          fi
+
+      - run: npm run build --if-present
+
+      - name: Rename dotfiles for npm pack
+        run: ./scripts/pre-pack.sh
+
+      - name: Publish to npm
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Push version bump
+        if: env.BUMPED == 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add package.json package-lock.json
+          git commit -m "chore: bump version"
+          git push

package/.internal.json

@@ -0,0 +1,45 @@
+{
+  "$comment": "Files explicitly withheld from distribution to consumer repos",
+  "internal": [
+    "src/**",
+    "bin/**",
+    "tsconfig.json",
+    "scripts/**",
+    ".internal.json",
+    ".github/**",
+    ".gitignore",
+    ".tldrignore",
+    "docs/**",
+    "README.md",
+    "CLAUDE.md",
+    "package.json",
+    "package-lock.json",
+    ".env.ai.example",
+    ".planning/**",
+    ".worktree/**",
+    "principles.md",
+    ".allhands/node_modules/**",
+    ".allhands/package-lock.json",
+    ".claude/envoy/**",
+    ".claude/backup-skills/**",
+    ".claude/settings.local.json",
+    ".git/**",
+    "scripts/**",
+    "target-lines.json",
+    ".reposearch/**",
+    "concerns.md",
+    "specs/**",
+    ".allhands/docs.local.json"
+  ],
+  "initOnly": [
+    ".allhands/skills/**",
+    "!.allhands/skills/claude-code-patterns/**",
+    "!.allhands/skills/harness-maintenance/**",
+    ".allhands/validation/**",
+    ".allhands/settings.json",
+    ".allhands/docs.json",
+    ".tldr/config.json",
+    ".claude/settings.json"
+  ],
+  "$distribution_comment": "What DOES get distributed: .allhands/ (flows, harness, agents, skills, schemas, validation), .claude/ (agents)"
+}

package/.tldr/config.json

@@ -0,0 +1,11 @@
+{
+  "semantic": {
+    "enabled": true,
+    "auto_reindex_threshold": 20,
+    "model": "bge-large-en-v1.5",
+    "default_language": "all"
+  },
+  "warm": {
+    "default_language": "all"
+  }
+}

package/.tldrignore

@@ -0,0 +1,90 @@
+# TLDR ignore patterns (gitignore syntax)
+# Auto-generated - review and customize for your project
+# Docs: https://git-scm.com/docs/gitignore
+
+# ===================
+# Dependencies
+# ===================
+node_modules/
+.venv/
+venv/
+env/
+__pycache__/
+.tox/
+.nox/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+vendor/
+Pods/
+
+# ===================
+# Build outputs
+# ===================
+dist/
+build/
+out/
+target/
+*.egg-info/
+*.whl
+*.pyc
+*.pyo
+
+# ===================
+# Binary/large files
+# ===================
+*.so
+*.dylib
+*.dll
+*.exe
+*.bin
+*.o
+*.a
+*.lib
+
+# ===================
+# IDE/editors
+# ===================
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# ===================
+# Security (always exclude)
+# ===================
+.env
+.env.*
+*.pem
+*.key
+*.p12
+*.pfx
+credentials.*
+secrets.*
+
+# ===================
+# Version control
+# ===================
+.git/
+.hg/
+.svn/
+
+# ===================
+# OS files
+# ===================
+.DS_Store
+Thumbs.db
+
+# ===================
+# Project-specific
+# Add your custom patterns below
+# ===================
+# large_test_fixtures/
+# data/
+bin/
+
+.reposearch/
+dist
+.planning/
+

package/CLAUDE.md

@@ -0,0 +1,6 @@
+@.allhands/flows/CORE.md
+
+When debugging .allhands , use the ah trace --help command for the tools to investigate the trace entries.
+
+When modifying ANY `.allhands/` files, discover the `harness-maintenance` skill via `ah skills list` and follow its routing table for domain-specific guidance.
+

package/README.md

@@ -0,0 +1,98 @@
+# All Hands CLI
+
+Internal CLI for the All Hands agentic harness.
+
+## Installation
+
+```bash
+cd .allhands/harness
+npm install
+```
+
+The `ah` command is automatically installed to `~/.local/bin/ah` when you run `npx all-hands init`. This shim finds and executes the project-local `.allhands/harness/ah` from any subdirectory.
+
+For local development, copy the shim to your PATH:
+```bash
+cp .allhands/harness/ah ~/.local/bin/ah
+```
+
+### Universal Ctags (for `ah docs` command)
+
+```bash
+# macOS
+brew install universal-ctags
+
+# Ubuntu/Debian
+sudo apt install universal-ctags
+```
+
+### AST-grep (for advanced code search)
+
+```bash
+# macOS
+brew install ast-grep
+
+# cargo
+cargo install ast-grep --locked
+```
+
+### Desktop Notifications (macOS)
+
+```bash
+brew install --cask notifier
+```
+
+## Language Servers (for LSP tool)
+
+```bash
+npm install -g typescript-language-server typescript pyright
+brew install swift  
+```
+
+## Environment Variables
+
+Check `.env.ai.example` for what you should populate `.env.ai` with.
+
+
+## Quick Start
+
+```bash
+ah <command>
+```
+
+The `ah` command works from any directory within an all-hands project.
+
+
+## Syncing to Target Repos
+
+The `sync` command distributes harness files from this repo to target repositories:
+
+```bash
+ah sync /path/to/target-repo
+```
+
+By default, sync preserves configuration files that target repos customize (settings, hooks, validation suites). These "init-only" files are only included during first-time setup or when explicitly requested.
+
+### The `--init` Flag
+
+Use `--init` to include init-only files — configuration defaults like `docs.json` that are normally withheld to avoid overwriting target-repo customizations:
+
+```bash
+# First-time setup — include all defaults
+ah sync /path/to/target-repo --init
+
+# Regular update — preserves target-repo configuration
+ah sync /path/to/target-repo
+```
+
+Use `--init` when setting up a new repo or resetting configuration to harness defaults. Omit it for routine updates. See `ah sync --help` for full options.
+
+## Project Settings
+
+Project-specific configuration lives in `.allhands/settings.json`:
+
+```json
+{
+  "$schema": "./harness/src/schemas/settings.schema.json",
+}
+```