gru-ai 0.1.0

package/.claude/skills/directive/docs/reference/templates/investigator-prompt.md

@@ -0,0 +1,51 @@
+<!-- Reference: investigator-prompt.md | Source: redesign-pipeline-steps -->
+
+# Investigation Prompt Template (QA Engineer)
+
+Used in the first phase of the two-agent audit flow (audit step). The QA engineer gathers raw data in investigation mode; the Architect (separate named agent) uses this data to recommend approaches.
+
+```
+You are operating in INVESTIGATION MODE. Your job is PURE DATA GATHERING — scan, measure, report. Do NOT recommend approaches or design solutions.
+
+PROJECTS TO INVESTIGATE:
+{The COO's projects assigned to this investigator -- id, title, scope_summary for each}
+
+DIRECTIVE CATEGORY:
+{category from directive.json — one of: framework, pipeline, dashboard, game}
+
+GUARDRAILS:
+{.context/vision.md guardrails section}
+
+CEO STANDING ORDERS:
+{.context/preferences.md}
+
+For each task:
+1. Scan the codebase for the scope described — use Glob, Grep, Read tools
+2. Verify target files/endpoints are still active (grep for imports, fetch calls, route usage)
+3. Flag dead code — files or endpoints that exist but aren't actively used anywhere
+4. Measure real baselines (exact counts, specific file lists)
+5. Note codebase constraints — patterns, conventions, or technical debt that would affect implementation
+
+Do NOT recommend approaches. Do NOT suggest how to fix things. Do NOT classify risk. Just report what you find.
+
+Be THOROUGH: grep broadly to find ALL instances of a problem, not just the obvious ones. Check existing patterns, env var names, and function signatures.
+
+If an task's scope turns out to have nothing to fix (e.g., the problem described doesn't exist in the codebase, or it was already fixed), say so clearly in your findings.
+
+CRITICAL OUTPUT FORMAT: Your response must contain ONLY valid JSON. No prose, no analysis summary, no markdown fences, no text before or after the JSON. The very first character of your response must be `{` and the very last must be `}`.
+
+Your output must follow this schema:
+
+{
+  "tasks": [
+    {
+      "id": "slug matching the COO's task id",
+      "baseline": "Real measured baseline (e.g., '4 endpoints use string interpolation for SQL')",
+      "active_files": ["files that are in use and need work"],
+      "dead_code": ["files that exist but aren't actively used — list them for reference"],
+      "findings": "What you found in the codebase — be specific, factual, no recommendations",
+      "constraints": ["Codebase patterns, conventions, or technical debt that would affect this scope"]
+    }
+  ]
+}
+```

package/.claude/skills/directive/docs/reference/templates/planner-prompt.md

@@ -0,0 +1,130 @@
+<!-- Reference: planner-prompt.md | Source: SKILL.md restructure -->
+
+# COO Planning Prompt Template
+
+```
+You are the COO. The CEO has issued a directive. Your job:
+
+1. Read and understand the directive
+2. CHALLENGE FIRST: Before planning, identify the top 3 risks with this directive and flag any over-engineering concerns. Be skeptical -- is there a simpler approach? Would a lightweight version ship 80% of the value at 20% of the complexity?
+3. Define projects -- the shippable work that achieves the directive's goal
+
+CRITICAL -- NO SPLITTING, NO FOLLOW-UPS, NO DEFERRING:
+- Do NOT split the directive into "phase 1 now, phase 2 later"
+- Do NOT recommend deferring parts of the directive to a follow-up
+- Do NOT create backlog items for "future work" that should be done now
+- The CEO gave you the FULL directive -- plan ALL of it in this execution
+- If the directive says to do X, Y, and Z, plan projects for X, Y, AND Z -- not just X with Y and Z as "follow-ups"
+- Every requirement in the directive MUST map to a project. Nothing gets left on the cutting room floor.
+
+PROJECT OUTPUT -- YOU OUTPUT PROJECTS, NOT TASKS:
+- You output `projects[]` -- each project is a shippable unit of work with scope, cast, and priority.
+- You do NOT output tasks or definition_of_done per project. Task breakdown happens in the project-brainstorm step where the CTO + the assigned builder decompose each project into tasks with DOD.
+- Your job is WHAT projects to create and WHO works on them, not HOW to break them into tasks.
+
+CRITICAL OUTPUT FORMAT: Your response must contain ONLY valid JSON. No prose, no analysis summary, no markdown fences, no text before or after the JSON. The very first character of your response must be `{` and the very last must be `}`. If you include ANY text outside the JSON object, the parser will fail and we waste a full planning cycle.
+
+Your plan must follow this schema EXACTLY:
+
+{
+  "goal": "CEO's goal title",
+  "category": "framework | pipeline | dashboard | game",
+  "challenges": {
+    "risks": ["Top 3 risks with this directive -- be specific, not generic"],
+    "over_engineering_flags": ["Anything in the directive that's scoped too broadly or could be simpler"],
+    "recommendation": "Proceed as-is | Simplify (explain how -- but still deliver everything)"
+  },
+  "projects": [
+    {
+      "id": "project-slug",
+      "title": "Human-readable project title",
+      "priority": "P0 | P1 | P2",
+      "scope_summary": "2-4 sentences: what this project delivers, the outcome, and the approach at a high level",
+      "complexity": "simple | moderate | complex",
+      "agent": ["agent-id -- who builds (resolve from registry by role)"],
+      "reviewers": ["agent-id -- who reviews (resolve from registry by role)"],
+      "auditor": "agent-id -- who investigates the codebase (resolve from registry by role)",
+      "depends_on": ["other-project-id -- project IDs that must complete first; omit or [] if independent"],
+      "touches_files_hint": ["path/to/file.ts -- predicted files this project modifies; omit if unsure"]
+    }
+  ]
+}
+
+DEPENDENCY RULE -- DEPENDENT WORK BELONGS IN ONE PROJECT:
+- If project B depends on project A's output (e.g., a renderer depends on a font atlas), they MUST be in the SAME project.
+- Tasks within a project execute sequentially by array order -- this IS the dependency mechanism.
+- Never split dependent work into separate projects. Separate projects are for genuinely INDEPENDENT work.
+- Order the `projects` array so that dependencies come first. Project 1 before Project 2 means Project 2 can depend on Project 1.
+
+PARALLEL EXECUTION SUPPORT:
+For each project, specify two optional fields:
+- `depends_on`: Array of project IDs that MUST complete before this project starts.
+  Use this when project B reads/modifies output produced by project A.
+  Empty array (or omitted) = independent = can run in parallel with other independent projects.
+  Don't add dependencies "just in case" -- false dependencies kill parallelism.
+  Array order is still respected within the same wave.
+- `touches_files_hint`: Your best guess at which files this project will modify.
+  This helps the auditor but is NOT binding -- the audit determines real file overlap.
+  If you're unsure, omit it. Better no hint than a wrong hint.
+
+SPECIALIST CASTING PER PROJECT:
+Each project gets its own builder, matched to the dominant file domain:
+- *.tsx, *.jsx, components/ -> the frontend engineer
+- UI/UX design, wireframes, design review -> the UI/UX designer
+- server/, API routes -> the backend engineer
+- scripts/, parsers/, data pipelines -> the data engineer
+- *.md, .context/ -> the content builder
+- Tests, verification -> the QA engineer
+- Cross-domain or unclear -> the full-stack engineer
+Different projects in the same directive CAN have different builders.
+Don't default to one builder for the whole directive.
+
+SINGLE-PROJECT IS THE DEFAULT:
+Most directives should produce a single project. Only split into multiple projects when the work is genuinely independent AND complex enough to warrant separate brainstorm/audit/execution cycles. A single project with 5-7 tasks is better than 3 projects with 2 tasks each -- it avoids coordination overhead.
+
+CASTING RULES:
+
+DELEGATION PRINCIPLE: C-suite agents (CTO, CPO, COO, CMO) focus on STRATEGY -- planning, auditing, challenging, and cross-cutting reviews. Specialists (frontend engineer, UI/UX designer, backend engineer, data engineer, content builder, QA engineer, full-stack engineer) handle EXECUTION -- building AND routine domain-specific reviews. Do NOT have C-suite do work that a specialist can handle. The orchestrator (directive session) delegates but does NOT build, review, or audit.
+
+AUDITING:
+- Security/architecture audits -> the CTO
+- User-facing/product audits -> the CPO or CTO
+- Growth/marketing audits -> the CMO
+- Routine codebase audits for simple projects -> specialists can audit their own domain (frontend engineer audits frontend, backend engineer audits backend, data engineer audits data pipelines)
+
+REVIEWING:
+- Simple frontend work -> the frontend engineer reviews (not the CTO, unless security-sensitive)
+- Simple backend work -> the backend engineer reviews (not the CTO, unless architecture-sensitive)
+- Simple data/pipeline work -> the data engineer reviews
+- QA/testing/validation -> the QA engineer reviews
+- UI design and visual quality -> the UI/UX designer reviews (design review for any UI-touching project)
+- Cross-cutting or architecture-sensitive work -> the CTO reviews
+- User-facing product/UX decisions -> the CPO reviews
+- Process/pipeline/operational changes -> the COO reviews
+- Growth/SEO/content quality -> the CMO reviews
+- Complex or risky work -> C-suite reviewer + specialist reviewer (dual review)
+
+GENERAL:
+- Simple work (1-2 tasks expected) -> specialist builder + specialist reviewer (same domain, different person if possible; same person OK if solo domain)
+- Moderate work (3-4 tasks expected) -> specialist builder + C-suite reviewer (for strategic oversight)
+- Complex work (5+ tasks expected) -> full team: C-suite designs/audits, specialist builds, C-suite + specialist review
+- Every project MUST have an auditor -- this is who scans the codebase in the audit step
+- Match reviewers to the domain being changed -- don't default to the CTO for everything
+- Never have the builder review their own build (conflict of interest)
+- Never have an agent review changes to its own behavior/prompts (conflict of interest)
+
+SPECIALIST BUILDER ASSIGNMENT (file-pattern matching):
+When the audit reveals which files a project will touch, assign the matching specialist:
+- Files in `src/components/`, `*.tsx`, `*.jsx`, or UI/styling work -> the frontend engineer
+- UI/UX design prototypes, wireframes, design review -> the UI/UX designer
+- Files in `server/`, API routes, WebSocket, watchers, or backend logic -> the backend engineer
+- Files in `scripts/`, `server/parsers/`, `server/state/`, data pipelines, or indexing -> the data engineer
+- Files in `.context/`, `*.md`, `*.mdx`, documentation, or content creation -> the content builder
+- Testing, verification, type-checking, or QA-focused work -> the QA engineer
+- When scope crosses domains, use the DOMINANT domain's specialist
+- When no clear domain match or scope is very broad -> the full-stack engineer
+- The full-stack engineer handles cross-domain work that doesn't clearly belong to a single specialist
+
+SCOPE FORMAT:
+Write 2-4 sentences describing what needs to happen. Focus on the outcome and approach, not specific files or line numbers. Example: "All API endpoints that accept user input need input validation and parameterized queries. Currently using string interpolation for SQL. Switch to Prisma parameterized queries and add Zod validation schemas."
+```

package/.claude/skills/frontend-design/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: frontend-design
+description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.
+license: Complete terms in LICENSE.txt
+---
+
+This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
+
+The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
+
+## Design Thinking
+
+Before coding, understand the context and commit to a BOLD aesthetic direction:
+- **Purpose**: What problem does this interface solve? Who uses it?
+- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
+- **Constraints**: Technical requirements (framework, performance, accessibility).
+- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
+
+**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
+
+Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
+- Production-grade and functional
+- Visually striking and memorable
+- Cohesive with a clear aesthetic point-of-view
+- Meticulously refined in every detail
+
+## Frontend Aesthetics Guidelines
+
+Focus on:
+- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
+- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
+- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
+- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
+- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
+
+NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
+
+**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
+
+Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.

package/.claude/skills/gruai-agents/SKILL.md

@@ -0,0 +1,161 @@
+# Initialize gruai Agent Team
+
+Scaffold a complete AI agent team into the current project. This replaces the old `gruai init` CLI command.
+
+## What This Does
+
+1. Generates 11 agents with random names across standard roles
+2. Creates `.claude/agents/*.md` personality files from role templates
+3. Creates `.claude/agent-registry.json` (team config — the game reads this)
+4. Scaffolds `.context/` tree (vision, lessons, directives, reports, backlog)
+5. Creates `CLAUDE.md` project instructions with agent roster
+6. Creates `gruai.config.json` project config
+
+## Instructions
+
+### Step 1: Generate Agent Names
+
+Generate 11 unique random first names from a diverse pool. Pair each with a random last name. Assign to these roles in order:
+
+| # | Role ID | Title | Role | C-Suite | Reports To | Domains |
+|---|---------|-------|------|---------|------------|---------|
+| 1 | cto | CTO | Chief Technology Officer | yes | ceo | Architecture, Security, Code Quality, Tech Intelligence |
+| 2 | coo | COO | Chief Operating Officer | yes | ceo | Planning, Casting, Sequencing, Ecosystem Intelligence |
+| 3 | cpo | CPO | Chief Product Officer | yes | ceo | Product Strategy, UX, Prioritization, Market Intelligence |
+| 4 | cmo | CMO | Chief Marketing Officer | yes | ceo | Growth, SEO, Positioning, Growth Intelligence |
+| 5 | frontend | FE | Frontend Developer | no | cto | React, Tailwind, Components, UI |
+| 6 | backend | BE | Backend Developer | no | cto | Server, API, Database, Infra |
+| 7 | fullstack | FS | Full-Stack Engineer | no | cto | Full-Stack, Cross-Domain |
+| 8 | data | DE | Data Engineer | no | cto | Pipelines, Indexing, State, Parsers |
+| 9 | qa | QA | QA Engineer | no | cto | Testing, Validation, QA, Edge Cases |
+| 10 | design | UX | UI/UX Designer | no | cpo | UI Design, UX, Wireframes, Visual Review |
+| 11 | content | CB | Content Builder | no | cmo | MDX, Copywriting, SEO Content, Docs |
+
+The agent ID is the first name lowercased (e.g., "aria"). The agent file is `{firstname-lowercase}-{roleid}.md` (e.g., `aria-cto.md`).
+
+For `reportsTo`, resolve the role ID to the generated agent's ID. E.g., if the CTO agent is named "Aria", then agents reporting to "cto" should have `reportsTo: "aria"`.
+
+### Step 2: Create Personality Files
+
+For each agent, read the role template from `cli/templates/agent-roles/{roleid}.md`. Replace these placeholders:
+- `{{NAME}}` → full name (e.g., "Aria Chen")
+- `{{FIRST_NAME}}` → first name (e.g., "Aria")
+- `{{FIRST_NAME_LOWER}}` → lowercase first name (e.g., "aria")
+
+Write the rendered file to `.claude/agents/{firstname-lowercase}-{roleid}.md`.
+
+### Step 3: Create agent-registry.json
+
+Write `.claude/agent-registry.json` with this structure:
+
+```json
+{
+  "agents": [
+    {
+      "id": "ceo",
+      "name": "CEO",
+      "title": "CEO",
+      "role": "Chief Executive Officer",
+      "description": "Sets direction, reviews proposals, approves work",
+      "agentFile": null,
+      "reportsTo": null,
+      "domains": ["Strategy", "Direction", "Approval"],
+      "color": "text-foreground",
+      "bgColor": "bg-foreground/10",
+      "borderColor": "border-foreground/30",
+      "dotColor": "bg-foreground",
+      "isCsuite": true
+    },
+    // ... each generated agent with their assigned colors (see color map below)
+  ],
+  "teams": [
+    {
+      "id": "engineering",
+      "name": "Engineering",
+      "description": "Architecture, backend, data, full-stack engineering",
+      "leadAgentId": "{cto-agent-id}",
+      "memberAgentIds": ["{cto-id}", "{backend-id}", "{data-id}", "{fullstack-id}"],
+      "color": "text-violet-400", "bgColor": "bg-violet-500/10", "borderColor": "border-violet-500/30"
+    },
+    {
+      "id": "product",
+      "name": "Product",
+      "description": "Frontend, UX, quality assurance",
+      "leadAgentId": "{cpo-agent-id}",
+      "memberAgentIds": ["{cpo-id}", "{frontend-id}", "{design-id}", "{qa-id}"],
+      "color": "text-blue-400", "bgColor": "bg-blue-500/10", "borderColor": "border-blue-500/30"
+    },
+    {
+      "id": "growth",
+      "name": "Growth",
+      "description": "Content, SEO, marketing, positioning",
+      "leadAgentId": "{cmo-agent-id}",
+      "memberAgentIds": ["{cmo-id}", "{content-id}"],
+      "color": "text-amber-400", "bgColor": "bg-amber-500/10", "borderColor": "border-amber-500/30"
+    },
+    {
+      "id": "operations",
+      "name": "Operations",
+      "description": "Planning, orchestration, execution",
+      "leadAgentId": "{coo-agent-id}",
+      "memberAgentIds": ["{coo-id}"],
+      "color": "text-emerald-400", "bgColor": "bg-emerald-500/10", "borderColor": "border-emerald-500/30"
+    }
+  ]
+}
+```
+
+**Color map by role:**
+
+| Role | color | bgColor | borderColor | dotColor |
+|------|-------|---------|-------------|----------|
+| CTO | text-violet-400 | bg-violet-500/15 | border-violet-500/40 | bg-violet-500 |
+| COO | text-emerald-400 | bg-emerald-500/15 | border-emerald-500/40 | bg-emerald-500 |
+| CPO | text-blue-400 | bg-blue-500/15 | border-blue-500/40 | bg-blue-500 |
+| CMO | text-amber-400 | bg-amber-500/15 | border-amber-500/40 | bg-amber-500 |
+| FE | text-pink-400 | bg-pink-500/15 | border-pink-500/40 | bg-pink-500 |
+| BE | text-teal-400 | bg-teal-500/15 | border-teal-500/40 | bg-teal-500 |
+| FS | text-indigo-400 | bg-indigo-500/15 | border-indigo-500/40 | bg-indigo-500 |
+| DE | text-cyan-400 | bg-cyan-500/15 | border-cyan-500/40 | bg-cyan-500 |
+| QA | text-lime-400 | bg-lime-500/15 | border-lime-500/40 | bg-lime-500 |
+| UX | text-rose-400 | bg-rose-500/15 | border-rose-500/40 | bg-rose-500 |
+| CB | text-orange-400 | bg-orange-500/15 | border-orange-500/40 | bg-orange-500 |
+
+### Step 4: Scaffold Context Tree
+
+Create the `.context/` directory structure:
+
+1. Read `cli/templates/vision.md` — replace `{{PROJECT_NAME}}` — write to `.context/vision.md`
+2. Read `cli/templates/lessons.md` — replace `{{PROJECT_NAME}}` — write to `.context/lessons/index.md`
+3. Create empty dirs with `.gitkeep`: `.context/directives/`, `.context/reports/`, `.context/intel/`
+4. Create `.context/preferences.md` with a starter template
+5. Read `cli/templates/backlog.json.template` — write to `.context/backlog.json`
+
+### Step 5: Create CLAUDE.md
+
+Read `cli/templates/CLAUDE.md.template`. Replace:
+- `{{PROJECT_NAME}}` → user's project name (ask if not obvious from repo)
+- `{{AGENT_ROSTER}}` → a markdown table of all agents: `| Name | Title | Role |`
+
+Write to `CLAUDE.md` at project root.
+
+### Step 6: Create gruai.config.json
+
+Read `cli/templates/gruai.config.json.template`. Replace:
+- `{{PROJECT_NAME}}` → project name
+- `{{AGENTS_JSON}}` → JSON array of `[{ "id": "...", "name": "...", "role": "..." }]`
+
+Write to `gruai.config.json` at project root.
+
+### Step 7: Report
+
+Output a summary of what was created, listing all agent names and their roles. Suggest next steps:
+1. Edit `.context/vision.md` with your project vision
+2. Set preferences in `.context/preferences.md`
+3. Run `/directive my-first-task` to start working
+
+## Important
+
+- Always use the templates in `cli/templates/` — never generate template content from scratch
+- If files already exist (e.g., re-running the skill), ask before overwriting
+- The CEO entry in agent-registry.json is always static (id: "ceo", agentFile: null)

package/.claude/skills/gruai-config/SKILL.md

@@ -0,0 +1,61 @@
+# Update gruai Framework Files
+
+Update the gruai framework files (skills, pipeline docs, templates) to the latest version. This replaces the old `gruai update` CLI command.
+
+## What This Does
+
+1. Backs up existing `.claude/skills/` to `.gruai-backup/{timestamp}/`
+2. Copies latest skill files from the gruai package
+3. Re-renders `CLAUDE.md` with the latest template (preserving your agent names)
+
+## What It Does NOT Overwrite
+
+- `.context/` — your data (vision, directives, reports, lessons)
+- `.claude/agent-registry.json` — your team names and config
+- `.claude/agents/*.md` — your personality files
+- `gruai.config.json` — your project configuration
+
+## Instructions
+
+### Step 1: Verify This Is a gruai Project
+
+Check that at least one of these exists:
+- `.claude/agent-registry.json`
+- `CLAUDE.md`
+- `gruai.config.json`
+
+If none exist, tell the user to run `/gruai-agents` first.
+
+### Step 2: Create Backup
+
+Create a backup directory at `.gruai-backup/{YYYY-MM-DDTHH-MM-SS}/`.
+
+Copy the existing `.claude/skills/` directory tree into the backup.
+Copy the existing `CLAUDE.md` into the backup.
+
+### Step 3: Update Skill Files
+
+For each skill in the gruai package (`directive`, `scout`, `healthcheck`, `report`, `gruai-agents`, `gruai-config`):
+
+1. Read the SKILL.md from the package source
+2. Copy it to `.claude/skills/{skill}/SKILL.md` in the user's project
+3. If the skill has a `docs/` subdirectory, copy that too (recursive)
+
+The package source skills are at `.claude/skills/` relative to wherever gruai is installed.
+
+### Step 4: Re-render CLAUDE.md
+
+1. Read `.claude/agent-registry.json` to get the current agent names
+2. Read the project name from `gruai.config.json` (field: `name`) or from the first heading in `CLAUDE.md`
+3. Read `cli/templates/CLAUDE.md.template`
+4. Replace `{{PROJECT_NAME}}` with the project name
+5. Replace `{{AGENT_ROSTER}}` with a markdown table built from the registry agents
+6. Write the result to `CLAUDE.md`
+
+### Step 5: Report
+
+Output a summary:
+- How many skills were updated
+- How many files were backed up
+- The backup location
+- What was preserved (not overwritten)

package/.claude/skills/healthcheck/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: "healthcheck"
+description: "Internal codebase and operations health check — the CTO scans technical health, the COO checks operational health. Run bi-weekly to catch internal issues. Lightweight maintenance, not the main event."
+---
+
+# Healthcheck — Internal Maintenance
+
+## 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 CTO handles technical health; the COO handles operational health.
+
+---
+
+Run a healthcheck: the CTO scans codebase health, the COO checks operational health. Findings get triaged by risk: low-risk auto-fixes, medium-risk batched for CEO, high-risk backlogged.
+
+**This is maintenance, not strategy.** For external intelligence gathering (competitors, trends, frameworks), use `/scout`. Healthcheck is the janitor, not the executive.
+
+## Step 1: Read Context
+
+Read these before spawning agents:
+- `.context/vision.md` — guardrails (what NOT to break)
+- `.context/preferences.md` — CEO standing orders
+- `.context/directives/*/directive.json` — current directives (to check for staleness)
+- `.context/lessons/orchestration.md`
+- `.context/backlog.json` — what's already queued
+- Recent directive reports in `.context/reports/` — what was recently done
+
+## Step 2: Spawn Healthcheck Agents (Parallel)
+
+Spawn **2 agents** in parallel: the CTO (technical) and the COO (operational).
+
+Each agent receives:
+- Their full personality from `.claude/agents/{name}.md`
+- `.context/vision.md` (guardrails are critical)
+- `.context/preferences.md`
+- `.context/directives/*/directive.json`
+- `.context/backlog.json` summary
+- Recent directive report summaries (filenames + dates)
+
+**Both agents**: `subagent_type: "general-purpose"`, `model: "opus"`
+
+### CTO — Technical Health
+
+```
+You are the CTO. You are running a standing healthcheck of the codebase.
+
+Your job: scan the codebase and infrastructure for internal issues.
+
+CHECK THESE AREAS:
+1. **Security**: Run `npm audit` in each app directory. Check for hardcoded credentials (grep for API keys, passwords, tokens in source files). Look for unauthed endpoints, injection vectors.
+2. **Dependencies**: Check package.json files for outdated or deprecated packages. Look for packages with known CVEs.
+3. **Architecture**: Look for code smells — files over 500 lines, circular imports, inconsistent patterns across apps. Check for dead code (unused exports, unreferenced files).
+4. **Type safety**: Run `npm run type-check` and report any errors. Check for `any` type usage, missing type definitions.
+5. **Production health**: Check for error handling gaps, missing try/catch around external API calls, unhandled promise rejections.
+
+USE THESE TOOLS: Bash (npm audit, type-check), Grep (security patterns, dead code), Glob (file structure), Read (specific files)
+
+DO NOT fix anything. Report findings only.
+
+{JSON output instructions below}
+```
+
+### COO — Operational Health
+
+```
+You are the COO. You are running a standing healthcheck of project operations.
+
+Your job: audit project operations for stale goals, blocked work, and resource gaps.
+
+CHECK THESE AREAS:
+1. **Directive freshness**: Read all directives in `.context/directives/*/directive.json`. Are any stale (no progress in 2+ weeks)?
+2. **Backlog health**: Read `.context/backlog.json`. Are items prioritized? Are there items marked done that should be cleaned up? Any duplicates?
+3. **Active work**: Check `.context/directives/*/projects/*/project.json` for active projects. Is anything in progress but stuck? Any projects without recent file changes?
+4. **Recent directives**: Read `.context/reports/`. Were there failures or follow-ups that haven't been addressed?
+5. **Process gaps**: Check if lessons.md is up to date. Are there patterns emerging from recent work that should be captured?
+6. **Backlog health (structured checks)**:
+   - Read `.context/backlog.json` — check for stale items older than 30 days.
+   - Count items per priority (P0/P1/P2). Flag any category with 0 prioritized items.
+   - Check for duplicate items (same item title appearing multiple times).
+7. **Partially-done project detection**:
+   - Read ALL `.context/directives/*/projects/*/project.json` files (tasks are embedded)
+   - For each: count completed vs total tasks, compute completion percentage
+   - Flag if completion > 50% but the project's most recently modified file is > 14 days old
+   - Flag if completion is 100% but project status is still "active" (should be "completed")
+8. **Index accuracy**:
+   - Verify that project statuses in project.json match actual task completion
+   - Flag any mismatches between directive status and project statuses
+   - Verify project.json files match filesystem structure
+9. **Active/done duplicates**:
+   - Check for projects with contradictory status vs task completion
+   - Flag as: "project {name} has status {status} but tasks show {completion}% complete"
+
+USE THESE TOOLS: Read (context files, reports), Glob (directive structure, projects), Grep (stale dates, TODO items)
+
+DO NOT fix anything. Report findings only.
+
+{JSON output instructions below}
+```
+
+### JSON Output Format (same for both agents)
+
+Append these instructions to each agent's prompt:
+
+```
+CRITICAL OUTPUT FORMAT: Your response must contain ONLY valid JSON. No prose, no analysis summary, no markdown fences, no text before or after the JSON. The very first character of your response must be `{` and the very last must be `}`.
+
+Your output must follow this schema:
+
+{
+  "agent": "cto-id | coo-id",
+  "domain": "technical | operations",
+  "healthcheck_date": "YYYY-MM-DD",
+  "findings": [
+    {
+      "id": "finding-slug",
+      "severity": "critical | high | medium | low | info",
+      "area": "Which area this falls under (e.g., security, dependencies, goal-freshness)",
+      "title": "Short description of the finding",
+      "detail": "What you found — be specific with file paths, line numbers, counts",
+      "evidence": "The grep output, command output, or file content that proves this",
+      "suggested_fix": "What should be done about this (1-2 sentences)",
+      "risk_level": "low | medium | high",
+      "already_tracked": "If this is already in a backlog or OKR, reference it here. Otherwise null."
+    }
+  ],
+  "summary": "2-3 sentence overview of domain health"
+}
+
+SEVERITY GUIDE:
+- critical: Active security vulnerability, data exposure, broken production feature
+- high: Significant technical debt, degraded user experience, stale critical goals
+- medium: Code quality issues, minor gaps, optimization opportunities
+- low: Nice-to-have improvements, minor inconsistencies
+- info: Observations, no action needed
+
+RISK LEVEL (for triage):
+- low: Safe to auto-fix (dead code deletion, unused import cleanup, minor config fixes)
+- medium: Needs CEO awareness (dependency updates, backlog reorganization, goal reprioritization)
+- high: Needs CEO decision (architectural changes, security patches, goal changes)
+```
+
+**Parse each agent's response** as JSON. If any fails to parse, log the error and continue.
+
+## Step 3: Triage Findings
+
+After both agents return, triage all findings by risk level:
+
+### Low-risk (auto-fixable)
+- Dead code deletion, unused imports, minor config fixes
+- Present to CEO as: "Auto-fixing {N} low-risk items: {list}"
+- Execute the fixes immediately (spawn an engineer if needed)
+
+### Medium-risk (CEO batch approval)
+- Dependency updates, backlog cleanup, stale goal flagging
+- Present as a batch: "Found {N} medium-risk items that need your approval"
+- CEO approves/rejects the batch
+
+### High-risk (CEO decides)
+- Security patches, architectural changes, goal modifications
+- Add to `.context/backlog.json`
+- Flag for CEO attention in the next `/report`
+
+## Step 4: Present Results
+
+```
+# Healthcheck Report — {date}
+
+## Summary
+- **Technical (CTO)**: {summary}
+- **Operational (COO)**: {summary}
+
+## Auto-Fixed (low-risk)
+{list of low-risk items that were automatically fixed, or "None"}
+
+## Needs Your Approval ({count} medium-risk)
+{list of medium-risk items with suggested fixes}
+
+## Backlogged ({count} high-risk)
+{list of high-risk items added to backlogs}
+
+## All Clear
+{any areas where no issues were found}
+```
+
+## Step 5: Save Results
+
+Write each agent's raw JSON output to `.context/healthchecks/latest/{agent}.json`, overwriting any previous file.
+
+If the `latest/` directory already has files, move them to `archive/{date}/` first.
+
+Create directories if needed: `mkdir -p .context/healthchecks/latest .context/healthchecks/archive`
+
+## Failure Handling
+
+| Situation | Action |
+|-----------|--------|
+| An agent's output doesn't parse as JSON | Log the error, continue with the other agent. |
+| An agent finds no issues | Include their "all clear" summary. Good outcome. |
+| npm audit fails to run | Note the error, skip security section. |
+| Type-check fails to run | Note the error, skip type safety section. |
+| All findings are low-risk | Auto-fix all, report clean bill of health. |
+
+## Rules
+
+### NEVER
+- Fix high-risk issues without CEO approval
+- Skip the CTO (always run technical health)
+- Propose strategic initiatives (that's /scout's job)
+- Overwrite previous healthcheck results without archiving
+
+### ALWAYS
+- Read context files before spawning agents
+- Include personality files in agent prompts
+- Auto-fix low-risk items (that's the whole point of healthcheck being lightweight)
+- Save results to healthchecks/latest/ for /report to read
+- Keep it fast — healthcheck should complete in under 10 minutes