gru-ai 0.1.0

package/.claude/skills/walkthrough/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: "walkthrough"
+description: "Cognitive walkthrough — simulate real user scenarios against the current system to find gaps between ideal and actual. Takes an optional scenario name or 'all' to run standing scenarios. Run after major directives or periodically as a reality check."
+---
+
+# Walkthrough — Cognitive Walkthrough
+
+## Role Resolution
+
+Read `.claude/agent-registry.json` to map roles to agent names. Use each agent's `id` as the `subagent_type` when spawning. The CPO designs the ideal experience; the CTO traces the actual implementation.
+
+---
+
+Simulate user scenarios against the current system. Find what's broken, missing, or surprising.
+
+**The pattern:** For each scenario, design what SHOULD happen (ideal), trace what DOES happen (actual), report the gaps.
+
+**Arguments:** `$ARGUMENTS`
+- A specific scenario name (e.g., `ceo-runs-directive`) → run just that one
+- `all` → run all standing scenarios
+- A free-text scenario description (e.g., `"seller wants to see competitor prices"`) → ad-hoc walkthrough
+- Empty → list available scenarios and ask which to run
+
+## Step 1: Load Scenarios
+
+### If $ARGUMENTS is a scenario name or "all":
+
+Read standing scenarios from `.context/lessons/scenarios.md`.
+
+Each scenario has:
+- **Name**: slug identifier
+- **Actor**: who is performing the action (CEO, seller, shopper, developer)
+- **Trigger**: what starts the flow ("CEO types /directive improve-security")
+- **Goal**: what the actor wants to achieve
+- **Critical path**: the steps that MUST work for the scenario to succeed
+
+If `all`, load all scenarios. If a specific name, load just that one.
+
+### If $ARGUMENTS is free text:
+
+Treat it as an ad-hoc scenario. Spawn the CPO to formalize it:
+
+```
+You are the CPO. The CEO described a user scenario informally:
+
+"{$ARGUMENTS}"
+
+Formalize it into this structure:
+{
+  "name": "slug-name",
+  "actor": "who is doing this",
+  "trigger": "what starts the flow",
+  "goal": "what the actor wants to achieve",
+  "critical_path": [
+    "Step 1: what should happen first",
+    "Step 2: what should happen next",
+    ...
+  ],
+  "success_criteria": "how do you know the scenario succeeded"
+}
+
+Think from the ACTOR's perspective, not the system's. What does the actor expect at each step? What would surprise or frustrate them?
+
+CRITICAL OUTPUT FORMAT: First character must be `{`, last must be `}`. JSON only.
+```
+
+### If $ARGUMENTS is empty:
+
+Read `.context/lessons/scenarios.md` and list available scenarios:
+
+```
+Available scenarios:
+1. ceo-runs-directive — CEO issues a directive, wants it handled without blocking
+2. ceo-morning-review — CEO opens dashboard, wants to know what happened overnight
+3. ...
+
+Which scenario to walk through? (or describe a new one)
+```
+
+Use AskUserQuestion with the scenario names as options.
+
+## Step 2: Design the Ideal (per scenario)
+
+For each scenario, spawn the CPO to design the **ideal experience** — what SHOULD happen if everything worked perfectly.
+
+The CPO receives:
+- Their personality file
+- The scenario definition
+- `.context/vision.md` — so the ideal aligns with the north star
+- `.context/preferences.md` — CEO expectations
+
+```
+You are the CPO. You are designing the IDEAL user experience for this scenario. Don't look at the current implementation — design from scratch what the perfect flow would be.
+
+SCENARIO:
+- Actor: {actor}
+- Trigger: {trigger}
+- Goal: {goal}
+
+For each step of the critical path, describe:
+1. What the actor does
+2. What the system should do in response
+3. What the actor sees/experiences
+4. How long it should take (instant / seconds / minutes / async)
+5. What would frustrate the actor at this step
+
+Then describe the END STATE: what does "success" look like from the actor's perspective?
+
+Think like a product designer, not an engineer. The actor doesn't care about checkpoints, worktrees, or JSON schemas. They care about: did the thing work? Was it fast? Did I have to babysit it?
+
+CRITICAL OUTPUT FORMAT: First character must be `{`, last must be `}`. JSON only.
+
+{
+  "scenario": "{name}",
+  "ideal_flow": [
+    {
+      "step": 1,
+      "actor_action": "what the actor does",
+      "system_response": "what should happen",
+      "actor_experience": "what they see/feel",
+      "timing": "instant | seconds | minutes | async",
+      "frustration_risk": "what could annoy the actor here"
+    }
+  ],
+  "end_state": "what success looks like",
+  "key_expectations": ["the non-negotiable things the actor expects"]
+}
+```
+
+## Step 3: Trace the Actual (per scenario)
+
+For each scenario, spawn the CTO to trace what ACTUALLY happens in the current system. The CTO reads code, config, and skill files to follow the real execution path.
+
+The CTO receives:
+- Their personality file
+- The scenario definition
+- The CPO's ideal flow (from Step 2)
+- `.context/lessons/` topic files — known issues
+- `.context/preferences.md`
+
+```
+You are the CTO. You are tracing what ACTUALLY happens in the current system for this scenario. Read the real code and config — don't guess.
+
+SCENARIO:
+- Actor: {actor}
+- Trigger: {trigger}
+- Goal: {goal}
+- Critical path: {steps}
+
+IDEAL FLOW (from the CPO):
+{CPO's ideal_flow JSON}
+
+For each step of the ideal flow, trace what the current system actually does:
+1. Read the relevant files (SKILL.md, agent files, code)
+2. Follow the execution path step by step
+3. Note where reality matches the ideal
+4. Note where reality DIVERGES from the ideal
+5. Note where the system does NOTHING (missing functionality)
+
+Be thorough. Grep for entry points, read the actual instructions, trace the branching logic. Don't assume — verify.
+
+CRITICAL OUTPUT FORMAT: First character must be `{`, last must be `}`. JSON only.
+
+{
+  "scenario": "{name}",
+  "actual_flow": [
+    {
+      "ideal_step": 1,
+      "ideal_expectation": "what the CPO said should happen",
+      "actual_behavior": "what the system actually does",
+      "status": "match | diverge | missing | broken",
+      "evidence": "file:line or config entry that proves this",
+      "notes": "explanation of the gap, if any"
+    }
+  ],
+  "gaps_found": [
+    {
+      "id": "gap-slug",
+      "severity": "critical | major | minor | cosmetic",
+      "type": "missing | broken | wrong | slow | confusing",
+      "description": "what's wrong",
+      "ideal": "what should happen",
+      "actual": "what does happen",
+      "evidence": "file:line",
+      "suggested_fix": "how to close the gap"
+    }
+  ],
+  "working_well": ["things that match the ideal — acknowledge what's good"]
+}
+```
+
+## Step 4: Synthesize Gaps
+
+After all scenarios are traced, consolidate the findings:
+
+1. **Deduplicate** — the same gap may appear in multiple scenarios
+2. **Prioritize** — critical gaps that block the actor's goal come first
+3. **Cross-reference** — gaps that appear in 2+ scenarios are systemic
+4. **Classify effort** — quick fix (< 1 hour), medium (half day), large (1+ days)
+
+## Step 5: Present to CEO
+
+```
+# Walkthrough Report — {date}
+
+## Scenarios Walked: {count}
+
+### {Scenario Name}
+**Actor**: {actor} | **Goal**: {goal}
+
+**Ideal vs Actual:**
+| Step | Ideal | Actual | Status |
+|------|-------|--------|--------|
+| 1 | {ideal} | {actual} | ✅ match / ⚠️ diverge / ❌ missing |
+| 2 | ... | ... | ... |
+
+**Gaps Found: {count}**
+- [{severity}] **{description}** — {type}
+  Ideal: {what should happen}
+  Actual: {what does happen}
+  Fix: {suggested fix} ({effort})
+
+**Working Well:**
+- {things that matched the ideal}
+
+(repeat per scenario)
+
+## Systemic Gaps (appear in 2+ scenarios)
+- **{gap}** — found in: {scenario list}
+
+## Summary
+- Total gaps: {count} ({critical}, {major}, {minor})
+- Scenarios fully passing: {count}/{total}
+- Top 3 fixes by impact: {list}
+```
+
+Then ask the CEO:
+- "Create directive from gaps" — bundle gaps into a directive in directives/
+- "Add to backlog" — write gaps to the relevant goal's backlog
+- "Note only" — just keep the report
+
+## Step 6: Save Report
+
+Write the full report to `.context/reports/walkthrough-{date}.md`
+
+If gaps were approved as a directive, create it in `.context/directives/`.
+
+## Standing Scenarios File
+
+If `.context/lessons/scenarios.md` doesn't exist, create it with starter scenarios on first run. The CEO and team add scenarios over time as new flows become important.
+
+## Failure Handling
+
+| Situation | Action |
+|-----------|--------|
+| The CPO can't formalize ad-hoc scenario | Ask CEO to clarify the scenario |
+| The CTO can't find the entry point for a step | Mark as "missing — no implementation found" |
+| A scenario has no gaps | Report it as passing — this is good news |
+| scenarios.md doesn't exist | Create it with starter scenarios, then run |
+
+## Rules
+
+### NEVER
+- Skip the ideal design (Step 2) — the whole point is comparing ideal vs actual
+- Have the same agent design ideal AND trace actual — separate perspectives prevent bias
+- Mark a gap as "minor" if it blocks the actor's goal — that's critical by definition
+- Trace the actual by reading docs/comments — read the real code/config
+
+### ALWAYS
+- Design ideal BEFORE tracing actual — don't let current state constrain the ideal
+- Include evidence (file:line) for every gap — no hand-waving
+- Acknowledge what's working well — not just gaps
+- Save the report even if no gaps found (it's a health signal)
+- Use the CPO for ideal (product thinking) and the CTO for actual (technical tracing)

package/.claude/skills/webapp-testing/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: webapp-testing
+description: Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.
+license: Complete terms in LICENSE.txt
+---
+
+# Web Application Testing
+
+To test local web applications, write native Python Playwright scripts.
+
+**Helper Scripts Available**:
+- `scripts/with_server.py` - Manages server lifecycle (supports multiple servers)
+
+**Always run scripts with `--help` first** to see usage. DO NOT read the source until you try running the script first and find that a customized solution is abslutely necessary. These scripts can be very large and thus pollute your context window. They exist to be called directly as black-box scripts rather than ingested into your context window.
+
+## Decision Tree: Choosing Your Approach
+
+```
+User task → Is it static HTML?
+    ├─ Yes → Read HTML file directly to identify selectors
+    │         ├─ Success → Write Playwright script using selectors
+    │         └─ Fails/Incomplete → Treat as dynamic (below)
+    │
+    └─ No (dynamic webapp) → Is the server already running?
+        ├─ No → Run: python scripts/with_server.py --help
+        │        Then use the helper + write simplified Playwright script
+        │
+        └─ Yes → Reconnaissance-then-action:
+            1. Navigate and wait for networkidle
+            2. Take screenshot or inspect DOM
+            3. Identify selectors from rendered state
+            4. Execute actions with discovered selectors
+```
+
+## Example: Using with_server.py
+
+To start a server, run `--help` first, then use the helper:
+
+**Single server:**
+```bash
+python scripts/with_server.py --server "npm run dev" --port 5173 -- python your_automation.py
+```
+
+**Multiple servers (e.g., backend + frontend):**
+```bash
+python scripts/with_server.py \
+  --server "cd backend && python server.py" --port 3000 \
+  --server "cd frontend && npm run dev" --port 5173 \
+  -- python your_automation.py
+```
+
+To create an automation script, include only Playwright logic (servers are managed automatically):
+```python
+from playwright.sync_api import sync_playwright
+
+with sync_playwright() as p:
+    browser = p.chromium.launch(headless=True) # Always launch chromium in headless mode
+    page = browser.new_page()
+    page.goto('http://localhost:5173') # Server already running and ready
+    page.wait_for_load_state('networkidle') # CRITICAL: Wait for JS to execute
+    # ... your automation logic
+    browser.close()
+```
+
+## Reconnaissance-Then-Action Pattern
+
+1. **Inspect rendered DOM**:
+   ```python
+   page.screenshot(path='/tmp/inspect.png', full_page=True)
+   content = page.content()
+   page.locator('button').all()
+   ```
+
+2. **Identify selectors** from inspection results
+
+3. **Execute actions** using discovered selectors
+
+## Common Pitfall
+
+❌ **Don't** inspect the DOM before waiting for `networkidle` on dynamic apps
+✅ **Do** wait for `page.wait_for_load_state('networkidle')` before inspection
+
+## Best Practices
+
+- **Use bundled scripts as black boxes** - To accomplish a task, consider whether one of the scripts available in `scripts/` can help. These scripts handle common, complex workflows reliably without cluttering the context window. Use `--help` to see usage, then invoke directly. 
+- Use `sync_playwright()` for synchronous scripts
+- Always close the browser when done
+- Use descriptive selectors: `text=`, `role=`, CSS selectors, or IDs
+- Add appropriate waits: `page.wait_for_selector()` or `page.wait_for_timeout()`
+
+## Reference Files
+
+- **examples/** - Examples showing common patterns:
+  - `element_discovery.py` - Discovering buttons, links, and inputs on a page
+  - `static_html_automation.py` - Using file:// URLs for local HTML
+  - `console_logging.py` - Capturing console logs during automation

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gruai contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,206 @@
+<p align="center">
+  <strong>Your AI dev team, visualized.</strong>
+</p>
+
+# gruai
+
+[![MIT License](https://img.shields.io/badge/license-MIT-green)](LICENSE) [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)](https://www.typescriptlang.org/) [![Status](https://img.shields.io/badge/status-alpha-orange)]()
+
+<p align="center">
+  <img src="docs/assets/demo.gif" alt="gruai pixel-art office simulation" width="720" />
+</p>
+
+Watch your AI agents work in a pixel-art office. gruai turns Claude Code sessions
+into a living simulation -- autonomous agents sitting at desks, writing code,
+reviewing PRs, and shipping features while you grab coffee.
+
+No other tool does this. Devin is $500/mo and headless. CrewAI is YAML config files.
+gruai gives you a real-time office where you can *see* your team think.
+
+---
+
+## Quickstart
+
+```bash
+git clone https://github.com/andrew-yangy/gruai.git
+cd gruai && npm install
+npm run dev
+```
+
+Then in Claude Code, run `/gruai-agents` to scaffold your AI team. The skill
+generates agent personalities, a team registry, and a welcome directive so your
+team has something to work on immediately. Open [http://localhost:5173](http://localhost:5173)
+to see the pixel-art office.
+
+---
+
+## What You Get
+
+### Pixel-Art Office Simulation
+Your agents aren't abstract boxes on a kanban board. They're characters in an
+office -- walking to their desks, typing at keyboards, gathering around a
+whiteboard to brainstorm. The office is a live view of your project's real state.
+
+### Autonomous Agent Teams
+Define roles (planner, builder, reviewer, scout) and gruai handles the rest.
+Agents pick up directives, decompose them into projects and tasks, build code,
+review each other's work, and report back. You approve or redirect -- they execute.
+
+### Directive Pipeline
+Every piece of work flows through a structured pipeline: triage, planning, audit,
+build, review, completion. Lightweight tasks skip the heavy steps automatically.
+No ceremony for small fixes, full rigor for big features.
+
+### Custom Teams
+Create your own agent roles with markdown templates in `.claude/agents/`. Give
+them personalities, specializations, and memory. The office simulation renders
+them as unique characters.
+
+### Live Dashboard
+Session kanban, activity tracking, one-click terminal focus, approval actions,
+prompt history, and usage insights. Everything you need to manage 10+ concurrent
+Claude Code sessions without losing your mind.
+
+---
+
+## Two Ways to Use gruai
+
+### Clone and run (recommended)
+
+```bash
+git clone https://github.com/andrew-yangy/gruai.git
+cd gruai
+npm install
+npm run dev
+```
+
+Then run `/gruai-agents` in Claude Code to scaffold your team. The dashboard
+discovers all Claude Code sessions from `~/.claude/` automatically -- no config needed.
+
+### Install as npm package
+
+```bash
+npm install gruai
+npm start
+```
+
+Then run `/gruai-agents` in Claude Code to scaffold agents into your project.
+
+---
+
+## How It Works
+
+```
+Your repo                              gruai
+┌─────────────────────┐               ┌──────────────────────────────┐
+│ .context/           │               │                              │
+│   directives/       │  file watch   │  Directive    Agent          │
+│     {id}/           ├──────────────>│  Pipeline  -> Casting        │
+│       directive.json│               │                              │
+│       projects/     │               │  Session      Pixel-Art     │
+│                     │               │  Scanner  --> Office UI      │
+│ .claude/            │               │                              │
+│   agents/           │  session      │  Process      Live           │
+│     {role}.md       │  discovery    │  Discovery -> Dashboard      │
+│                     ├──────────────>│                              │
+│ ~/.claude/          │               │  WebSocket    React          │
+│   projects/         │               │  Server   --> Frontend       │
+│     *.jsonl         │               │                              │
+└─────────────────────┘               └──────────────────────────────┘
+```
+
+1. **Directive Pipeline** reads `.context/directives/` and orchestrates work
+   through triage, planning, build, and review phases
+2. **Session Scanner** watches `~/.claude/projects/` for live Claude Code sessions
+   and extracts metadata (model, branch, current tool, files being edited)
+3. **Process Discovery** maps running Claude processes to terminal panes via
+   `ps` and `lsof` -- supports tmux, iTerm2, Warp, and Terminal.app
+4. **Pixel-Art Office** renders agents as characters in an isometric office,
+   with real-time animations tied to actual session state
+
+---
+
+## Terminal Support
+
+Session discovery works on any OS. Terminal focus requires OS integration:
+
+| Environment | Focus | Send Input | Notes |
+|-------------|:-----:|:----------:|-------|
+| iTerm2 + tmux | Yes | Yes | AppleScript + tmux pane switching |
+| iTerm2 native | Yes | Yes | AppleScript with session ID |
+| Warp + tmux | Yes | Yes | CGEvents + tmux |
+| Warp native | Yes | No | CGEvents tab navigation |
+| Terminal.app + tmux | Yes | Yes | Bring to front + tmux |
+
+> Linux and Windows support coming soon.
+
+---
+
+## Optional: Claude Code Hooks
+
+gruai works without hooks. For instant status detection (permission prompts, idle
+states), add hooks to `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "Notification": [
+      {
+        "matcher": "permission_prompt",
+        "hooks": [{ "type": "command", "command": "bash -c 'INPUT=$(cat); curl -s -X POST http://localhost:4444/api/events -H \"Content-Type: application/json\" -d \"{\\\"type\\\":\\\"permission_prompt\\\",\\\"sessionId\\\":\\\"$(echo $INPUT | jq -r .session_id)\\\",\\\"message\\\":\\\"$(echo $INPUT | jq -r .message)\\\"}\"'" }]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [{ "type": "command", "command": "bash -c 'INPUT=$(cat); curl -s -X POST http://localhost:4444/api/events -H \"Content-Type: application/json\" -d \"{\\\"type\\\":\\\"stop\\\",\\\"sessionId\\\":\\\"$(echo $INPUT | jq -r .session_id)\\\"}\"'" }]
+      }
+    ]
+  }
+}
+```
+
+Without hooks, status updates via filesystem scanning (slight delay). With hooks,
+updates are instant.
+
+---
+
+## Tech Stack
+
+| Layer | Stack |
+|-------|-------|
+| Server | Node.js + WebSocket + SQLite + chokidar |
+| Frontend | React 19 + Vite + Zustand + Tailwind v4 + shadcn/ui |
+| Game | Canvas 2D pixel-art engine, 16x16 tile system |
+| Terminal | AppleScript (iTerm2) + CGEvents (Warp) + tmux CLI |
+| Data | Zero external services -- reads from `~/.claude/` locally |
+
+---
+
+## Scripts
+
+```bash
+npm run dev          # Dev mode (server + client with hot reload)
+npm run dev:server   # Server only (port 4444)
+npm run dev:client   # Vite dev only
+npm start            # Production server (serves built assets)
+npm run build        # Production build
+npm run type-check   # TypeScript check
+npm run lint         # ESLint
+```
+
+## Claude Code Skills
+
+```
+/gruai-agents        # Scaffold AI agent team (replaces gruai init)
+/gruai-config        # Update framework files to latest version
+/directive           # Run work through the directive pipeline
+/report              # CEO dashboard report
+/healthcheck         # Internal codebase health check
+/scout               # External intelligence gathering
+```
+
+---
+
+## License
+
+[MIT](LICENSE)

package/cli/templates/CLAUDE.md.template

@@ -0,0 +1,57 @@
+# {{PROJECT_NAME}} — Claude Code Rules
+
+## What This Is
+{{PROJECT_NAME}} uses gruai, an autonomous AI company framework. See `.context/vision.md` for the full vision.
+
+## Context Tree Structure
+
+```
+.context/
+|-- vision.md                           # System vision (read first)
+|
+|-- directives/                         # ALL work lives here: Directive > Project > Task
+|   |-- {id}/
+|   |   |-- directive.json              # Pipeline state, weight, category
+|   |   |-- directive.md                # CEO brief
+|   |   +-- projects/
+|   |       |-- {project-id}/
+|   |       |   +-- project.json       # Tasks[], DOD, agents -- THE source of truth
+|   |       +-- ...
+|   +-- ...
+|
+|-- reports/                            # CEO dashboard reports
+|   |-- daily-{date}.md
+|   +-- weekly-{date}.md
+|
+|-- lessons/                            # Flat, topic-based knowledge
+|   +-- index.md
+|
+|-- backlog.json                        # Prioritized work items
+|-- preferences.md                      # CEO standing orders
+```
+
+## How to Read the Context Tree
+
+- **"What should we do now?"** -> Read `directives/*/directive.json` for active directives
+- **Planning a feature:** -> Read `vision.md` + relevant directive context + `lessons/`
+- **Building a feature:** -> Read project.json for tasks
+- **After completing work:** -> Update project.json tasks, update `lessons/` if new patterns
+
+## Key Conventions
+
+- Directory names = entity IDs. `directives/pipeline-v2/` means `directive.id = "pipeline-v2"`
+- project.json is THE source of truth for a project including all its tasks
+- Tasks are embedded in project.json -- no separate task files
+- Directives discovered via glob: `directives/*/directive.json`
+- Projects discovered via glob: `directives/*/projects/*/project.json`
+
+## Agent Team
+
+{{AGENT_ROSTER}}
+
+## Pipeline Enforcement
+- **ALL work goes through the `/directive` pipeline.** The pipeline is weight-adaptive: lightweight tasks skip some steps; heavyweight gets the full process.
+- NEVER spawn builder/engineer agents directly. Use `/directive` which handles reviews, scope, and completion verification.
+
+## Git Operations
+NEVER perform git operations without explicit user approval.