@arthai/agents 1.0.5 → 1.0.6

package/dist/plugins/compass/commands/planning.md

@@ -58,7 +58,86 @@ Map user choices:
 
 Store the resolved mode as `DEBATE_MODE` (values: `lite`, `fast`, `full`).
 
-### 3. Codebase Scan
+### 3. Phase 0: Spec Generation (before debate)
+
+Before any debate rounds, the PM generates a **spec doc** that becomes the foundation for all subsequent work. This ensures user stories and edge cases are defined BEFORE architecture decisions.
+
+**Create the specs directory:**
+```bash
+mkdir -p .claude/specs
+```
+
+**Spawn PM agent (subagent_type="product-manager", model="sonnet") for spec generation only:**
+
+Prompt:
+```
+You are a Product Manager generating a spec doc for the feature "{feature-name}".
+
+Feature brief: {FEATURE_BRIEF}
+
+Generate a spec doc with these sections:
+
+## User Stories
+Write 3-7 user stories covering the happy path and key error states.
+Format: "As a [user type], I want [action], so that [outcome]"
+Each story must have:
+- **Story ID**: US-1, US-2, etc.
+- **Priority**: P0 (must-have for launch) or P1 (important but deferrable)
+- **Acceptance**: specific testable condition that proves this story is done
+
+Example:
+  US-1 [P0]: As a new developer, I want to install the toolkit with one command,
+  so that I can start using it without manual configuration.
+  Acceptance: `npx @arthai/agents install forge .` succeeds and skills are available.
+
+## User Journey
+Step-by-step flow from the user's first interaction to completion.
+Include:
+- **Happy path**: numbered steps (1. User does X → 2. System responds Y → ...)
+- **Decision points**: where the user makes a choice (mark with ◆)
+- **Error branches**: where things can go wrong (mark with ✗ and show recovery path)
+
+Format as a text flowchart:
+```
+1. User discovers feature
+2. User does [action]
+   ◆ Decision: [choice A] or [choice B]
+   → Choice A: proceed to step 3
+   → Choice B: proceed to step 5
+3. System responds with [result]
+   ✗ Error: [what went wrong] → Recovery: [how to fix]
+4. ...
+```
+
+## Edge Cases
+Structured list of what can go wrong. For each:
+- **ID**: EC-1, EC-2, etc.
+- **Scenario**: what triggers this edge case
+- **Expected behavior**: what should happen (not crash, not hang)
+- **Severity**: Critical (blocks user) / High (degrades experience) / Medium (inconvenience)
+- **Linked story**: which user story this edge case relates to
+
+## Success Criteria
+Measurable outcomes tied to user stories. These become the acceptance criteria
+that /implement and /qa use to validate the implementation.
+- Each criterion references a story ID
+- Each criterion is binary: pass or fail, no subjective judgment
+```
+
+**Write the output to `.claude/specs/{feature-name}.md`** with this frontmatter:
+
+```markdown
+---
+feature: {feature-name}
+generated: {ISO date}
+stories: {count}
+edge_cases: {count}
+---
+```
+
+**Store the spec content as `FEATURE_SPEC`** — this is injected into the shared context block for all debate participants.
+
+### 4. Codebase Scan
 
 Spawn an `explore-light` subagent (model: haiku) to scan for relevant files:
 
@@ -68,7 +147,7 @@ prompt: "For a feature called '{feature-name}', find: (1) related backend routes
 
 Store the result as `CODEBASE_CONTEXT`.
 
-### 4. Create Team + Tasks
+### 5. Create Team + Tasks
 
 Create team: `planning-{feature-name}`
 
@@ -76,12 +155,13 @@ Create these tasks:
 
 | Task | Owner | Subject |
 |------|-------|---------|
-| 1 | product-manager | Define product spec for {feature-name} |
+| 0 | product-manager | Generate spec doc for {feature-name} (Phase 0 — already done above) |
+| 1 | product-manager | Define product scope for {feature-name} (uses spec as input) |
 | 2 | architect | Design technical plan for {feature-name} |
 | 3 (if --design) | design-thinker | Create design brief for {feature-name} |
 | 4 (if not --lite) | devils-advocate | Challenge scope and feasibility for {feature-name} |
 
-### 5. Build Shared Context Block
+### 6. Build Shared Context Block
 
 Compose this block to inject into every teammate's spawn prompt:
 
@@ -95,6 +175,11 @@ Auth: {AUTH_APPROACH}
 ## Feature: {feature-name}
 {FEATURE_BRIEF}
 
+## Spec Doc (from Phase 0)
+{FEATURE_SPEC}
+
+(Full spec at: .claude/specs/{feature-name}.md)
+
 ## Relevant Codebase
 {CODEBASE_CONTEXT}
 
@@ -114,13 +199,13 @@ This planning session runs in {DEBATE_MODE} mode.
 - If DA recommends KILL and user overrides, record as USER OVERRIDE in the plan.
 ```
 
-### 6. Spawn Teammates (ALL IN ONE MESSAGE — parallel)
+### 7. Spawn Teammates (ALL IN ONE MESSAGE — parallel)
 
 Spawn all teammates in a **single message** with multiple Task tool calls:
 
 **Always spawn:**
 - **product-manager** (subagent_type="product-manager", model="opus")
-  - Prompt: "{SHARED_CONTEXT}\n\nYou are the PM. Own the 'what' and 'why'.\n\nIn Round 1, you LEAD with your scope claim. Format your must-haves as:\n  [M1] requirement — BECAUSE reason\n  [M2] ...\nMaximum 5 MUST-HAVEs. Also list NICE-TO-HAVEs with CUT-IF conditions, EXPLICIT EXCLUSIONS, and success metrics.\n\nIn Round 2, you COUNTER the architect's approach: does it deliver user value, is it over-engineered, what is the time-to-value?\n\nIn Round 3 (full mode only), you DEFEND against the devil's advocate's risk case. Accept or reject each risk with evidence."
+  - Prompt: "{SHARED_CONTEXT}\n\nYou are the PM. Own the 'what' and 'why'. You generated the spec doc in Phase 0 — your user stories and edge cases are in the shared context above. Use them as the foundation for your scope claim.\n\nIn Round 1, you LEAD with your scope claim. Each must-have should trace to one or more user stories (reference by ID, e.g., 'US-1, US-3'). Format your must-haves as:\n  [M1] requirement — BECAUSE reason (traces to US-X)\n  [M2] ...\nMaximum 5 MUST-HAVEs. Also list NICE-TO-HAVEs with CUT-IF conditions, EXPLICIT EXCLUSIONS, and success metrics.\n\nIn Round 2, you COUNTER the architect's approach: does it deliver the user journey as specified? Is it over-engineered? What is the time-to-value? Reference edge cases the approach doesn't handle.\n\nIn Round 3 (full mode only), you DEFEND against the devil's advocate's risk case. Accept or reject each risk with evidence. Reference user stories to justify why a must-have cannot be cut."
 
 - **architect** (subagent_type="architect", model="opus")
   - Prompt: "{SHARED_CONTEXT}\n\nYou are the Architect. Own the 'how'.\n\nIn Round 1, you COUNTER the PM's scope from a feasibility lens. Challenge feasibility, flag hidden complexity, identify scope creep vectors, propose a counter-scope.\n\nIn Round 2, you LEAD with your technical approach: API contract, DB changes, architecture decision + WHY, task breakdown with S/M/L/XL estimates, implementation cost, dependencies, risks.\n\nIn Round 3 (full mode only), you DEFEND against the devil's advocate's risk case. Accept or reject each risk with evidence. Keep it simple for early-stage. Push back on scope that doesn't match the development stage."
@@ -140,7 +225,7 @@ Spawn all teammates in a **single message** with multiple Task tool calls:
 - **gtm-expert** (subagent_type="gtm-expert", model="sonnet")
   - Prompt: "{SHARED_CONTEXT}\n\nYou are the GTM Expert. Own distribution and launch strategy. Advise on positioning, viral mechanics, and launch sequencing. Challenge the team on how users will discover and adopt this feature. Your output feeds into Round 3 as additional evidence for the devil's advocate."
 
-### 7. Structured Debate Protocol
+### 8. Structured Debate Protocol
 
 Facilitate the following rounds in sequence. Each phase completes before the next begins.
 
@@ -279,7 +364,7 @@ Each matched item is flagged as a RISK NOTE in the plan.
 
 ---
 
-### 8. Convergence Logic
+### 9. Convergence Logic
 
 **Plan is APPROVED when ALL of the following are true after all applicable rounds complete:**
 - Rounds 1 and 2 have zero UNRESOLVED items
@@ -296,7 +381,7 @@ If user overrides a KILL recommendation, record as `USER OVERRIDE` in the plan.
 
 In lite and fast modes, skip convergence checks for rounds that were not run. Apply only the checks applicable to completed rounds.
 
-### 9. Scope Lock
+### 10. Scope Lock
 
 After convergence, compute a `scope_hash`:
 - Concatenate all locked MUST-HAVE strings from Round 1 in order
@@ -305,7 +390,7 @@ After convergence, compute a `scope_hash`:
 
 When `/implement` loads the plan, it can verify the hash against the locked must-haves to detect tampering.
 
-### 10. Write Plan File + Present to User
+### 11. Write Plan File + Present to User
 
 Synthesize teammate outputs into a structured plan and **write it to `.claude/plans/{feature-name}.md`** using the Write tool. This file is read by `/implement` to auto-configure the implementation team.
 
@@ -317,6 +402,7 @@ feature: {feature-name}
 debate_mode: {DEBATE_MODE}
 scope_hash: {SHA-256 of locked must-haves}
 da_confidence: {HIGH|MEDIUM|LOW|N/A}
+spec: specs/{feature-name}.md
 layers:
   - frontend  # include if ANY frontend tasks exist
   - backend   # include if ANY backend tasks exist
@@ -324,6 +410,9 @@ layers:
 
 # Planning Summary: {feature-name}
 
+## Spec Reference
+See `.claude/specs/{feature-name}.md` for user stories, user journey, edge cases, and success criteria.
+
 ## Problem & User Segment (from PM)
 ...
 
@@ -394,7 +483,7 @@ layers:
 
 Present the plan to the user for review.
 
-### 11. Cleanup
+### 12. Cleanup
 
 After user reviews the plan:
 - Send shutdown_request to all teammates.

package/dist/plugins/compass/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/project-setup.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/dist/plugins/compass/hooks/project-setup.sh

@@ -0,0 +1,109 @@
+#!/bin/bash
+# hooks/project-setup.sh — SessionStart hook: first-run project setup for marketplace installs.
+#
+# Runs on every SessionStart. Checks for marker file .claude/.toolkit-setup-done.
+# If missing (or version is stale): creates CLAUDE.md from template, injects managed block,
+# updates .gitignore with toolkit markers.
+#
+# Templates are read from ${CLAUDE_PLUGIN_ROOT}/templates/ (bundled with the plugin).
+
+set -euo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-}"
+MARKER_FILE="$PROJECT_DIR/.claude/.toolkit-setup-done"
+
+# Exit silently if CLAUDE_PLUGIN_ROOT is not set (not running from a plugin context)
+if [ -z "$PLUGIN_ROOT" ]; then
+    exit 0
+fi
+
+TEMPLATES_DIR="$PLUGIN_ROOT/templates"
+TEMPLATE_CLAUDE="$TEMPLATES_DIR/CLAUDE.md.template"
+TEMPLATE_BLOCK="$TEMPLATES_DIR/CLAUDE.md.managed-block"
+
+# Exit silently if templates are not bundled
+if [ ! -f "$TEMPLATE_CLAUDE" ] || [ ! -f "$TEMPLATE_BLOCK" ]; then
+    exit 0
+fi
+
+# Read toolkit version from VERSION file (bundled alongside plugin)
+TOOLKIT_VERSION="0.0.0"
+if [ -f "$PLUGIN_ROOT/VERSION" ]; then
+    TOOLKIT_VERSION=$(cat "$PLUGIN_ROOT/VERSION" 2>/dev/null | tr -d '[:space:]' || echo "0.0.0")
+fi
+
+MANAGED_START="<!-- >>> claude-agents toolkit (DO NOT EDIT THIS BLOCK) >>> -->"
+MANAGED_END="<!-- <<< claude-agents toolkit <<< -->"
+GITIGNORE_START="# >>> claude-agents managed (DO NOT EDIT THIS BLOCK) >>>"
+
+# Check marker file — skip if current version is already set up
+if [ -f "$MARKER_FILE" ]; then
+    STORED_VERSION=$(cat "$MARKER_FILE" 2>/dev/null | tr -d '[:space:]' || echo "")
+    if [ "$STORED_VERSION" = "$TOOLKIT_VERSION" ]; then
+        exit 0
+    fi
+fi
+
+CLAUDE_MD="$PROJECT_DIR/CLAUDE.md"
+GITIGNORE="$PROJECT_DIR/.gitignore"
+
+# 1. Create CLAUDE.md from template if it doesn't exist (never overwrite existing)
+if [ ! -f "$CLAUDE_MD" ]; then
+    PROJECT_NAME=$(basename "$PROJECT_DIR")
+    sed "s/{{PROJECT_NAME}}/$PROJECT_NAME/g" "$TEMPLATE_CLAUDE" > "$CLAUDE_MD"
+fi
+
+# 2. Inject managed block into CLAUDE.md if missing, or update if version is stale
+if [ -f "$CLAUDE_MD" ]; then
+    BLOCK_CONTENT=$(cat "$TEMPLATE_BLOCK")
+    NEW_BLOCK=$(printf '%s\n<!-- version: %s -->\n%s\n%s' \
+        "$MANAGED_START" "$TOOLKIT_VERSION" "$BLOCK_CONTENT" "$MANAGED_END")
+
+    if ! grep -qF "$MANAGED_START" "$CLAUDE_MD"; then
+        # Block missing — append it
+        printf '\n\n%s\n' "$NEW_BLOCK" >> "$CLAUDE_MD"
+    else
+        # Block exists — update if version changed
+        EXISTING_VERSION=$(grep -o '<!-- version: [^>]* -->' "$CLAUDE_MD" 2>/dev/null | head -1 | sed 's/<!-- version: //;s/ -->//' | tr -d '[:space:]' || echo "")
+        if [ "$EXISTING_VERSION" != "$TOOLKIT_VERSION" ]; then
+            # Replace block contents between markers
+            tmp=$(mktemp)
+            in_block=false
+            wrote_block=false
+            while IFS= read -r line; do
+                if echo "$line" | grep -qF "$MANAGED_START"; then
+                    in_block=true
+                    printf '%s\n' "$NEW_BLOCK" >> "$tmp"
+                    wrote_block=true
+                    continue
+                fi
+                if echo "$line" | grep -qF "$MANAGED_END"; then
+                    in_block=false
+                    continue
+                fi
+                if ! $in_block; then
+                    echo "$line" >> "$tmp"
+                fi
+            done < "$CLAUDE_MD"
+            mv "$tmp" "$CLAUDE_MD"
+        fi
+    fi
+fi
+
+# 3. Update .gitignore with toolkit marker block if missing
+if [ ! -f "$GITIGNORE" ] || ! grep -qF "$GITIGNORE_START" "$GITIGNORE" 2>/dev/null; then
+    GITIGNORE_BLOCK=$(printf '%s\n.claude/.toolkit-last-seen-sha\n.claude/.toolkit-setup-done\n.claude/.claude-agents.conf\n%s' \
+        "$GITIGNORE_START" "# <<< claude-agents managed <<<")
+    if [ ! -f "$GITIGNORE" ]; then
+        printf '%s\n' "$GITIGNORE_BLOCK" > "$GITIGNORE"
+    else
+        printf '\n\n%s\n' "$GITIGNORE_BLOCK" >> "$GITIGNORE"
+    fi
+fi
+
+# 4. Write marker file with current version
+mkdir -p "$PROJECT_DIR/.claude"
+printf '%s\n' "$TOOLKIT_VERSION" > "$MARKER_FILE"
+
+exit 0

package/dist/plugins/compass/templates/CLAUDE.md.managed-block

@@ -0,0 +1,123 @@
+## Engineering Principles (MANDATORY — applies to ALL work)
+
+### Research Before Fixing
+- **Never guess.** Before changing code, read the relevant source files, docs, and configs.
+- Understand WHY something is broken before attempting a fix.
+- If your first fix doesn't work, STOP. Don't try another guess. Re-read the code.
+- Use explore-light (Haiku, 1x cost) to scan the codebase before expensive agents investigate.
+
+### No Over-Engineering
+- **Do exactly what's needed.** Don't add abstractions, utilities, or frameworks unless the code already uses them.
+- Match existing patterns — run explore-light to find how similar code is structured before writing new code.
+- A bug fix touches the minimum files possible. A feature matches the existing architecture.
+- If you're creating a new class/helper/utility that nothing else in the codebase uses, you're over-engineering.
+
+### Test Before Shipping
+- **Run tests locally before pushing.** Never push untested code.
+- If the project has `/precheck`, run it. If it has `/qa`, run it in commit mode.
+- After fixing a bug, verify the fix AND verify nothing else broke (differential testing).
+- If 3+ consecutive fix attempts fail, STOP. Step back and reassess the root cause from scratch.
+
+### Deployment Safety
+- **Never modify production systems without explicit confirmation.**
+- Don't change deploy targets, CI pipeline structure, or infrastructure config silently.
+- Don't overwrite existing files during deployment without asking.
+- If a deployment breaks something, investigate before attempting to fix. Don't cascade.
+
+## Toolkit Awareness (MANDATORY — READ THIS FIRST)
+
+You have a **claude-agents toolkit** installed in this project. It provides specialized
+agents, skills, and hooks that handle domain-specific work better and cheaper.
+
+**You are the ORCHESTRATOR.** The triage router fires on every message with a routing
+table and SPEED score. Use it to decide: toolkit or you?
+
+### When to use the toolkit (SPEED score 2+):
+- **Multi-step workflows**: `/pr`, `/deploy`, `/planning`, `/implement`, `/qa`, `/ci-fix`
+  encode battle-tested sequences you'd otherwise do manually and forget steps
+- **Domain expertise**: SRE, QA, frontend, backend agents have project context baked in
+- **Cost savings**: Haiku/Sonnet agents handle 80% of tasks at 1/60th the cost of Opus
+- **Parallelism**: Team skills spawn multiple agents working simultaneously
+
+### When to use YOU directly (SPEED score 0-1):
+- **Quick lookups**: Read/Grep/Glob for finding a file, checking a value, reading code
+- **Small targeted edits**: 1-2 file changes where you already know what to do
+- **Complex reasoning**: Architecture decisions, debugging novel problems, nuanced tradeoffs
+- **Conversation flow**: Follow-up questions, clarifications, explaining code
+- **Creative problem-solving**: When the task doesn't fit any existing pattern
+- **Judgment calls**: Security reviews, design decisions, "should we even do this?"
+
+### The balance:
+The toolkit handles **process** (repeatable workflows, domain-specific checks, multi-step
+sequences). You handle **judgment** (reasoning, creativity, novel problems, architecture).
+
+A senior engineer doesn't do everything themselves — they delegate routine work and focus
+their expertise where it matters most. That's you. The toolkit is your team.
+
+**Don't over-delegate**: If it's faster to just Read a file and answer, do it.
+**Don't under-delegate**: If it's a 5-step workflow the toolkit has a skill for, use it.
+
+### Project Knowledge System
+
+If this project has been calibrated (`/calibrate`), deep context is available:
+
+- **`.claude/project-profile.md`** — Architecture patterns, coding conventions, domain model,
+  testing style. Read this before writing any code to match the project's patterns.
+- **`.claude/knowledge/`** — The toolkit's long-term memory for this project:
+  - `shared/conventions.md` — Coding rules learned from corrections. **Read before writing code.**
+  - `shared/domain.md` — Business rules beyond what's in the code. **Read before domain decisions.**
+  - `shared/vocabulary.md` — What the team calls things. **Use these terms.**
+  - `shared/patterns.md` — Architecture patterns. **Follow these when adding new code.**
+  - `agents/{your-name}.md` — Your past learning. **Read on session start.**
+  - **Write back** when you learn something new — corrections, discoveries, decisions.
+  - See `knowledge/README.md` for the full protocol.
+- **`.claude/knowledge/external/sources.md`** — Where team knowledge lives outside code
+  (Notion, Linear, Figma, etc.). Check before making decisions that might already be documented.
+
+## Session Start Behavior (MANDATORY)
+
+On your FIRST response in every new session, ALWAYS start with a brief status line
+using context from the SessionStart hook. Include:
+- Current branch + uncommitted file count
+- Docker/infra status (if problems detected)
+- Open PRs or assigned issues (if any)
+- Any red flags (pending migrations, expired tokens)
+
+Format: 1-3 compact lines before addressing the user's request. Example:
+```
+📋 project — main | 5 uncommitted | Docker: postgres ✓ redis ✓ | 2 open PRs
+```
+Then proceed with the user's actual request.
+
+**CRITICAL — Greetings and vague first messages**: If the user's first message is a
+greeting ("hey", "hi", "hello", "yo", "sup") or vague ("help", "what's up",
+"what should I work on") or ANY message under 5 words with no specific task —
+**ALWAYS use the `/onboard` skill**. Never respond to greetings yourself. The
+bootstrap hook status line is a quick snapshot — `/onboard` gives the real briefing
+with open PRs, issues, priorities, and actionable next steps.
+
+## Routing Trace (MANDATORY)
+
+On EVERY response, show a compact routing trace so the user understands the decision
+path. Place it at the end of your response in a dimmed block:
+
+```
+🔀 Routing: [what triage decided] → [agent/skill/tool used] ([cost tier])
+   Why: [1-line reason for this routing choice]
+```
+
+Examples:
+```
+🔀 Routing: backend bug fix → python-backend agent (Sonnet, 10x)
+   Why: touches backend/app/services/, needs CLAUDE.md context, SPEED=4
+```
+```
+🔀 Routing: file lookup → Grep (built-in, 0x)
+   Why: single-file search, no project context needed, SPEED=0
+```
+
+Rules:
+- Always show the SPEED score breakdown if score >= 2
+- Show which hook provided the context (triage-router, bootstrap, etc.)
+- If you chose NOT to use the triage router's suggestion, explain why
+- Skip the trace only for simple follow-up messages in an ongoing conversation

package/dist/plugins/compass/templates/CLAUDE.md.template

@@ -0,0 +1,111 @@
+# CLAUDE.md — {{PROJECT_NAME}}
+
+<!-- Generated by claude-agents install.sh --init -->
+<!-- TODO: Replace {{placeholders}} with your project details -->
+
+## Project Overview
+
+{{PROJECT_NAME}} is a {{DESCRIPTION}}.
+
+## Tech Stack
+
+- **Frontend**: <!-- TODO: e.g., Next.js 14, React 18, TypeScript, Tailwind -->
+- **Backend**: <!-- TODO: e.g., FastAPI, SQLAlchemy, PostgreSQL -->
+- **Auth**: <!-- TODO: e.g., Stytch, Auth0, Clerk -->
+- **Deploy**: <!-- TODO: e.g., Railway, Vercel, AWS -->
+
+## Project Structure
+
+```
+{{PROJECT_NAME}}/
+├── frontend/          <!-- TODO: Frontend directory -->
+├── backend/           <!-- TODO: Backend directory -->
+└── ...
+```
+
+## Key Architecture
+
+<!-- TODO: Describe your auth flow, API patterns, database schema, etc. -->
+
+## Local Dev Services
+
+<!-- TODO: Auto-populated by /scan or fill manually -->
+
+| Service  | Port | Directory | Start Command |
+|----------|------|-----------|---------------|
+| Frontend | <!-- TODO --> | frontend/ | <!-- TODO: e.g., npm run dev --> |
+| Backend  | <!-- TODO --> | backend/  | <!-- TODO: e.g., uvicorn app.main:app --reload --> |
+
+## Test Commands
+
+<!-- TODO: Auto-populated by /scan or fill manually -->
+
+| What | Command | Directory |
+|------|---------|-----------|
+| Backend tests | <!-- TODO: e.g., pytest --> | backend/ |
+| Backend lint | <!-- TODO: e.g., ruff check . --> | backend/ |
+| Frontend tests | <!-- TODO: e.g., npm test --> | frontend/ |
+| Frontend lint | <!-- TODO: e.g., npm run lint --> | frontend/ |
+| Type check | <!-- TODO: e.g., npx tsc --noEmit --> | frontend/ |
+| E2E tests | <!-- TODO: e.g., npx playwright test --> | frontend/ |
+
+## Infrastructure
+
+<!-- TODO: Auto-populated by /scan or fill manually -->
+
+| Platform | Service | Domain |
+|----------|---------|--------|
+| <!-- TODO: e.g., Railway --> | <!-- TODO --> | <!-- TODO --> |
+
+Health endpoints: <!-- TODO: e.g., /health, /api/health -->
+
+## Environments
+
+<!-- TODO: Auto-populated by /scan environments or /calibrate -->
+
+| Name | Type | URL | Health | Deploy | Branch |
+|------|------|-----|--------|--------|--------|
+| local | development | <!-- TODO --> | <!-- TODO: e.g., /health --> | manual | — |
+| <!-- TODO --> | <!-- TODO: staging/production/preview/canary --> | <!-- TODO --> | <!-- TODO --> | <!-- TODO --> | <!-- TODO --> |
+
+Access notes: <!-- TODO: e.g., Railway MCP for staging/prod. Env vars: .env.local, .env.staging -->
+
+## Domain
+
+<!-- TODO: Auto-populated by /scan or fill manually -->
+<!-- Describe what this app does, its core entities, and business rules. -->
+<!-- Used by qa-domain agent for domain-aware testing. -->
+
+## Running Locally
+
+```bash
+# TODO: Add your local development commands
+# Frontend
+cd frontend && npm run dev
+
+# Backend
+cd backend && source .venv/bin/activate && uvicorn app.main:app --reload
+```
+
+## Critical Rules
+
+<!-- TODO: Add project-specific rules, e.g.: -->
+- Never push to main directly — always create a PR
+- Secrets in .env.local only — never committed
+
+## Agent Customization
+
+The following agents/skills are managed by `claude-agents` (symlinked):
+- Run `~/.claude-agents/install.sh --status` to see what's linked
+- To override any portable file, replace the symlink with a regular file
+- Your override won't be touched by future syncs
+
+### Project-Specific Agents
+
+Add project-specific agents as regular files in `.claude/agents/`:
+- See `~/.claude-agents/examples/agents/` for templates (frontend, backend, ops, sre, qa)
+
+### Project-Specific Skills
+
+Add project-specific skills as regular directories in `.claude/skills/`:
+- See `~/.claude-agents/examples/skills/` for templates (ci-fix, qa, restart)

package/dist/plugins/counsel/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "counsel",
   "description": "AI consulting toolkit — client discovery, proposals, deliverables",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "author": {
     "name": "Arth AI"
   }

package/dist/plugins/counsel/VERSION

@@ -0,0 +1 @@
+1.0.6

package/dist/plugins/counsel/hooks/hooks.json

@@ -1,6 +1,16 @@
 {
   "hooks": {
     "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/project-setup.sh",
+            "timeout": 10
+          }
+        ]
+      },
       {
         "matcher": "",
         "hooks": [