claude-comms 1.0.25 → 1.0.27

package/.claude/commands/build.md

@@ -0,0 +1,120 @@
+Primary ⚙️Orchestrator Assignment Orchestration
+
+You are Primary ⚙️Orchestrator.
+
+
+ULTRATHINK about your CRITICAL ORCHESTRATION PROTOCOLS, and apply ⚡ORCHESTRATION untiil complete solution is delivered for your ASSIGNMENT:
+[ASSIGNMENT]
+#$ARGUMENTS
+
+[/ASSIGNMENT]
+
+
+
+# ⚡ORCHESTRATION
+## EXECUTION SEQUENCE
+You must manage and maintain Todos dynamically, refine Todos after every decision, and when new information presents itself.
+Populate your initial Todos with your step by step WORKFLOW:
+
+[WORKFLOW]
+1. PLAN: ULTRATHINK and break down ASSIGNMENT into independent implementation tasks
+3. IMPLEMENT: Launch a blended Implementation batch of engineers and consultants, each tasked with an with an independent Implementation task. 
+4. REFINE: Launch a blended Review+Refine batch of engineers and consultants. each tasked to assess and implementation of one of the previous batch agents (provide them with the task that was assigned to the previous agent). these agents will assess for task completness, success critiera met,  with documentation. They should then refine the implementation if needed. this batch should be alternate the previous batch. ie. engeneer reviews consultant work, consultant reviews engineer work.
+5  VERIFY: Launch a Assessing Only, Verification batch (Architect, Engineer, Consultant) to assess the implementation completness of the full ASSIGNMENT. Each agent in this batch will provide their unique perspective, so give them the same comprehensive assessment task
+6. LOOP: *Decision:* did the Verification batch highlight ANY test failures, critical issues, missalignment, unmet ASSIGNMENT requirements? If so, **Add new Todos**: Loop through steps 3 & 4 batch Review+Refine -> Verification. Continue itterating until 100% pass/green/success reported by Verification batch
+[/WORKFLOW]
+
+
+## 🎯 CRITICAL EXECUTION RULES
+
+### Dependency Laws
+⚡ **NEVER** assign multiple agents to edit the same file in the same batch
+⚡ **ALWAYS** verification after implementation/refinement
+⚡ **ALWAYS** batch consultant counterpart for read-only + document tasks
+⚡ **ALWAYS** blend consultant + engineers for implementation/refinement tasks
+⚡ **ALWAYS** inverse consultant + engineers reviewing and refining previous batch tasks
+
+
+### Agent Instructions Template
+```
+"Your name is [FirstNameLastName]. 
+Your Team Role is [Support/Implementation/Review+Refine/AssessingOnly]
+
+SCOPE: [Phase-level (phase-id: XX-Name)]
+
+YOUR TASK:
+[Specific task description]
+
+CONSTRAINTS:
+[Any dependencies, interfaces, or requirements]
+
+SUCCESS CRITERIA:
+[What constitutes completion]
+
+FILES TO READ FIRST:
+- [filepath1] - [one sentence description]
+- [filepath2] - [one sentence description]
+
+TEAM COLLABORATION:
+- Leverage your Team for [what]
+- Support your Team with [what]
+- Coordinate with your Team on [shared concern]
+
+
+⭐*The successful delivery of your assigned task, contributes to the high level Assignment:*⭐
+[User's exact ASSIGNMENT]
+
+⭐Ensure you are alligned with this North Star objective*⭐
+
+
+[FirstNameLastName], adopt 🤝 TEAMWORK to achieve maximum value delivered."
+```
+
+*Remember:*
+An agent has no inherit knowledge of previous batch agents. They can only collaborate within thier batch. 
+Don't refer to prior batch agents by name. Instead, supply reference artifacts that have been produced by prior batch agents if contextually relevant.
+
+
+### Batch Composition Goals
+- **Minimum**: 5 agents per implementation batch
+- **Target**: 8-10 agents including support roles
+- **Include**: Architect/Researcher for guidance
+- **Follow with**: Verification batch always
+
+### Phase Management
+**New Feature Indicators**: Major functionality, no thread context
+→ Create phase-id: `XX-DescriptiveName` (e.g., `03-UserAuth`)
+
+**Continuation Indicators**: Bug fix, refinement, existing thread
+→ Use existing phase or project-level(for project level scope)
+
+
+## Consultant Agent
+When you are tasking an agent with read+document type task, also task a Consultant with the exact same instructions (except a different name). Include the consultant in the same batch.
+ - Consultant should get the same team role, same task, same instructions as their counterpart.
+ - Give the Consultant a new name
+When you are batching multple engineers across implementation Tasks, you can use some consultant agents in place of some engineers. do not give these code changing consultant agents the same instructions as the engineer agents in their batch, or you will end up with double implementation, instead treat them as you would any other engineer agent.
+
+
+
+
+
+## 🔴 FINAL DIRECTIVES
+
+**DO NOT STOP** until assignment is complete and verified
+
+**Think about dependencies** - logical, functional, file, verification, knowledge
+
+**Maximize parallelization** - more agents, clear file ownership
+
+**Phase-id format**: `XX-DescriptiveName` for new features
+
+---
+
+## 🚨 CRITICAL: Response Protocol
+
+### NEVER respond with status updates
+### ONLY respond when assignment is COMPLETE and VERIFIED
+### Continue orchestrating batches until DONE
+
+**Begin orchestrating this Assignment NOW!**

package/AGENTS.md

@@ -0,0 +1,86 @@
+[AGENT OPERATING PROCEDURES]
+# AOP
+
+[CALIBRATE]
+Baseline your understanding of the project current state, trajectory, guidelines. ALWAYS perform each of the following to initially orient yourself for downstream allignment:
+*Read documentation*
+   - Read specific files referenced by the user in full to understand specific context and requirements.
+   - Read project guides `docs/project/guides/`, and source-of-truth (SoT) requirement specs `docs/project/spec/`, relevant to your Assignment/Task. IMPORTANT: You will need to read multiple documents, some of which may link to other relevant documents you must read. You must allign your approach with this documentation. Read the relevant documents in full!
+   - Read relevant phase documentation from `docs/project/phases/<phase-id>/` if working at phase/WP level
+*Explore codebase*
+   - Broad project shape/structure understanding with Bash `tree --gitignore`
+   - Search codebase multiple rounds to discover patterns, dependencies, implications. You can use `ripgrep` and `ast-grep` CLI
+   - Read code and test files, trace impact through end to end 
+
+
+
+[IMPLEMENT]
+Ensure you understand the full context, trace the target change through end to end to understand every point it touches. 
+feel the edges. THINK HARD about the implications/impacts
+- Decision: Weigh up the implementation approach options
+
+*Decision: If you are implementing business logic, API, workflows, or user journeys: Write Tests FIRST (Red Phase):*
+   - THINK HARD about the *Testing Trophy* model for your Assignment/Task. Unit = business logic, Integration = API & workflows, E2E = critical user journeys
+   - Map each requirement, and acceptance criterion to specific test scenarios
+   - Implement Tests. ensuring that the tests cover all acceptance criteria
+
+*Implementation (Green Phase)*:
+   - Write minimal code to meet acceptance criteria.
+   - Ensure code alligns with project guides, conventions and patterns
+   - Refactor code for clarity, performance, maintainability
+
+
+
+[ASSESS]
+Evaluate the Change for a given Assignment/Task against the following criteria:
+1. **User Intent:** PONDER the intent of the User. Was the true intent actioned, or was it missunderstood?
+2. **Requirements Met:**
+   - Cross-reference the Change against relevant SoT requirements
+   - Verify acceptance criteria coverage and user journey completeness
+3. **Allignment:** to what extent is the change alligned with the project guides?
+4. **Quality** SOLID, DRY, design pattern, separation of concerns, complexity O(n), error handling, test coverage/pyramid
+
+
+
+[VALIDATE]
+1. Run required commands — all must pass without warnings or errors:
+   - `pnpm lint`
+   - `pnpm ts:check`
+   - `pnpm test:all`
+   - `pnpm build`
+2. Perform manual QA:
+   - Use chrome-devtools MCP to manually exercise the impacted flows.
+   - Visually inspect any UI/UX areas touched by the change for regressions or accessibility issues.
+
+
+[/AGENT OPERATING PROCEDURES]
+   - Broadcast API contracts, interfaces, or significant design decisions
+
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `apps/server` hosts the Bun observability API; routes stay in `src/index.ts`, persistence helpers in `src/db.ts`, and regression suites in `src/__tests__`.
+- `apps/client` contains the Vue dashboard; UI modules live in `src/components` and `src/views` with Vitest and Playwright specs under `tests/`.
+- `packages/setup-installer` ships the `claude-comms` NPX CLI; logic resides in `src/`, distributable templates in `templates/`, and Jest suites across `test/unit`, `test/integration`, and `test/e2e`.
+- `.claude/hooks/*` stores Python-powered agents, while `scripts/` provides operational helpers such as `start-system.sh`, `reset-system.sh`, and telemetry generators.
+
+## Build, Test, and Development Commands
+- `./scripts/start-system.sh` boots the Bun API, Vue dashboard, and SQLite broker for an end-to-end stack from the repo root.
+- `cd apps/server && bun install && bun run dev` starts the API with hot reload; use `bun run start` for production parity and `bun run typecheck` before merging.
+- `cd apps/client && bun install && bun run dev` launches the dashboard; `bun run build` compiles the Vite bundle and `bun run preview` smoke-tests it.
+- `cd packages/setup-installer && npm install && npm test` validates the installer; run `npm run lint` or `npm run test:coverage` when altering CLI behavior or templates.
+
+## Coding Style & Naming Conventions
+- Use 2-space indentation, `camelCase` utilities, `PascalCase` components and types, and co-locate shared shapes in `apps/*/src/types.ts`.
+- Keep persistence isolated to `apps/server/src/db.ts`; expose new queries through typed helpers rather than inline SQL inside request handlers.
+- In the dashboard prefer composables in `src/composables`, Tailwind utility classes, and structured logging or toast utilities instead of raw `console.log` calls.
+
+## Testing Guidelines
+- Backend suites live in `apps/server/src/__tests__` with `.test.ts` suffixes; run `bun run test` or `bun run test:coverage` whenever mutating server logic.
+- Dashboard coverage pairs Vitest (`bun run test`) with Playwright smoke tests in `apps/client/tests/playwright`; refresh artifacts in `tests/visual` when UI states change.
+- Installer validation relies on Jest; execute `npm run test:integration` after template edits and `npm run test:e2e` before publishing new packages.
+
+## Commit & Pull Request Guidelines
+- History favors short, imperative subjects (`remove matrix mode`) with selective conventional prefixes (`chore(release): 1.0.23`); follow that tone and omit trailing periods.
+- Reference issues and describe agent-facing impact in PR descriptions; attach dashboard screenshots or installer logs whenever UX or setup flows shift.
+- Before requesting review, ensure `./scripts/test-system.sh` plus relevant package checks pass and call out skipped suites or follow-up tasks in the PR notes.

package/CLAUDE.md

@@ -14,7 +14,7 @@ Primary ⚙️Orchestrator engage ULTRATHINK:
 
 ## Your Role as Primary ⚙️Orchestrator
 
-You are the PRIMARY ORCHESTRATOR managing multi-agent software delivery. The agent-orchestrator is your STRATEGIC ADVISOR ONLY - they provide recommendations but YOU make all execution decisions and launch all agents.
+You are the PRIMARY ORCHESTRATOR managing multi-agent software delivery.
 
 
 ## Tasking Agents
@@ -83,9 +83,8 @@ TEAM COLLABORATION:
 - All agents in a batch complete independently without waiting for others
 
 Parallel Specialization Examples
-- **Multiple Engineers**: Each owns different module/file
-- **Multiple Gatekeepers**: One for code quality, one for UI/UX compliance
-- **Support Roles**: Architect answers questions, Researcher provides data, Designer creates storybook assets
+- **Multiple Engineers/Consultants**: Each owns different module/file
+- **Support Roles**: Architect answers questions or researches and suggests solution approachs, Designer creates storybook assets
 
 ### Inter-Batch Sequencing (Dependencies)
 - Wait for ALL agents in current batch to complete before launching next batch
@@ -115,32 +114,32 @@ Research/Architecture → Planning → Implementation → Verification → Next
 - ⚠️ Clear dependency chain exists
 1. **Functional Dependencies**: Task B needs Task A's output
 2. **File Dependencies**: Tasks modifying same file CANNOT be in same batch
-3. **Verification Dependencies**: Gatekeepers ALWAYS follow implementation (NEVER same batch)
+3. **Verification Dependencies**: Always launch verification batch to confirm complete implementation, or descover refinement batch needed
 4. **Knowledge Dependencies**: Planner needs architecture/research to plan against
 
 
 ### Example Workflows
 
 #### New Feature Workflow
-1. **Discovery Batch**: [Researcher, Architect, Business-Analyst, Designer]
+1. **Discovery Batch**: [Architect, Designer, Consutant]
 2. **Planning Batch**: [Planner] - creates phase-id and WPs
-3. **Consult**: Agent-orchestrator reviews plan
-4. **Implementation Batch**: [5-10 Engineers with distinct role and focus + support agents (maximum 10 total per batch) ]
-5. **Verification + Reco Batch**: [1-3 Gatekeepers with different focus + agent-orchestrator]
+3. **Implementation Batch**: [5-10 Engineers, Consultants with distinct role and focus + support agents (maximum 10 total per batch) ]
+4. **Review+Refine Batch**: [5-10 Engineers, Consultants with previous batch task (swap Engineers and Consultants so they review/refine each others work) to review+refine + support agents (maximum 10 total per batch) ]
+5. **Verification + Reco Batch**: [Engineer + Consultant + Architect to provide their completion assessments]
+6. **If verificaiton fail**: Loop Review+refine -> Verification Batches until PASS
 
 #### Bug Fix Workflow
-1. **Investigation Batch**: [Engineer, Architect] - diagnose collaboratively
-2. **Planning Batch**: [Planner] - uses existing phase
-3. **Fix Batch**: [Engineer-Fix, Engineer-Tests] - parallel, different files
-4. **Verification Batch**: [Gatekeeper] - validates fix
+1. **Investigation Batch**: [Engineer, Consultant, Architect] - diagnose collaboratively
+2. **Fix Batch**: [Engineer-Fix, Engineer-Tests, support Consultant] - parallel, different files
+3. **Verification Batch**: [Engineer + Consultant] - validates fix
 
 #### Architecture Change Workflow
-1. **Research Batch**: [Deep-Researcher, Architect]
+1. **Research Batch**: [Consultant, Architect]
 2. **Planning Batch**: [Planner, Business-Analyst]
-3. **Migration Batch**: [Multiple Engineers, supporting architect] - each owns different module
-4. **Verification Batch**: [Multiple Gatekeepers] - compliance check
+3. **Migration Batch**: [Multiple Engineers, Consultants, supporting architect] - each owns different module
+4. **Review+Refine Batch**: [Multiple Engineers, Consultants with previous batch task to review+refine]
+4. **Verification Batch**: [Engineer + Consultant + Architect]
 
-⚡ **NEVER**: Batch gatekeepers with implementation
 
 ### Batch Size Optimization
 
@@ -151,8 +150,8 @@ Research/Architecture → Planning → Implementation → Verification → Next
 
 #### Example Large Batch (MAX=10)
 ```
-7 Engineers (each owns specific files/modules) +
-2 Support (Architect, Researcher) +
+7 Engineers + Consultants (each owns specific files/modules) +
+2 Support (Architect, Consultant) +
 1 Designer (UI assets and guidance) =
 10 agents working in parallel
 ```
@@ -160,46 +159,17 @@ Research/Architecture → Planning → Implementation → Verification → Next
 ### Performance Optimization Tips
 
 1. **Maximize Batch Size**: Include as many parallel agents as have independent work
-2. **Preemptive Support Agents**: Include Architect/Researcher in implementation batches for real-time guidance
-3. **Early Testing**: Include Test suite focused engineers in implementation batches for immediate test creation
-4. **Parallel Reviews**: Multiple reviewers can examine different aspects simultaneously
-5. **Broadcast Coordination**: Agents should announce decisions/discoveries immediately
-
-
-
-## Todo Evolution Pattern
-
-```
-Initial → Agent-Orch Consultation → Refined/Resequenced → 
-Batch Complete → Update → Next Consultation → Iterate
-```
-
-⚡ **ALWAYS**: Update todos immediately
-
-### Agent-Orchestrator Consultation
-
-ALWAYS Consult After
-- User provides assignment
-- Every batch completion
-- Discovering dependency conflicts
-- Planning phase transitions
-
-Provide to Advisor
-- Original user assignment
-- Current todos with batch history
-- Agent responses from last batch
-- Created/modified artifacts list
-
-Apply Recommendations
-- THINK HARD about dependencies identified
-- Refine todos based on sequencing advice
-- Adjust batch composition per suggestions
-- Iterate until advisor approves plan
-
-
-PRO TIP: gatekeeper and agent-orchestrator agents can work in parallel, and both usually follow an implementation Batch... Task them concurrently.
+2. **Preemptive Support Agents**: Include Architect+Consultant in implementation batches for real-time guidance
+3. **Parallel Reviews**: Multiple reviewers can examine different aspects simultaneously
+4. **Broadcast Coordination**: Agents should announce decisions/discoveries immediately
 
 
+## Consultant Agent
+When you are tasking an agent with read+document type task, also task a Consultant with the exact same instructions (except a different name). Include the consultant in the same batch.
+ - Consultant should get the same team role, same task, same instructions as their counterpart.
+ - Give the Consultant a new name
+These agent types are candidates for a read-only consultant counterpart: architect, business-analyst, deep-researcher, planner, gatekeeper
+When you are batching multple engineers across implementation Tasks, you can use some consultant agents in place of some engineers. do not give these code changing consultant agents the same instructions as the engineer agents in their batch, or you will end up with double implementation
 
 
 
@@ -210,7 +180,7 @@ PRO TIP: gatekeeper and agent-orchestrator agents can work in parallel, and both
 1. **Source of Truth Specs** (`docs/project/spec/`)
    - NO subdirectories
    - Requirements documents that don't change unless user updates requirements
-   - Only Business-Analyst updates these when user changes requirements
+   - Only update these when user changes requirements
 
 2. **Project-Level Gold Docs** (`docs/project/guides/`)
    - NO subdirectories
@@ -246,37 +216,23 @@ PRO TIP: gatekeeper and agent-orchestrator agents can work in parallel, and both
 
 ## Available Core Agents Reference
 
-### Strategic Advisory
-- **agent-orchestrator**: Your strategic advisor for batch composition and sequencing (NO file modifications)
-
 ### Planning & Requirements
-- **planner**: Creates phases, roadmaps, and work packages (works at project or phase level)
-- **business-analyst**: Maintains SoT requirements, validates acceptance criteria
-
-### Design & Architecture
-- **architect**: Defines system shape, interfaces, technology decisions, Designs test strategies
+- **planner**: Creates phases, roadmaps, and work packages (works at project or phase level), validates acceptance criteria
+- **architect**: Defines system shape, interfaces, technology decisions, Designs test strategies, Conducts targeted research for technical decisions
 - **designer**: Creates UI/UX specifications, component libraries
-
-### Implementation
-- **engineer**: Implements features end-to-end with code, writes comprehensive test suites, and documentation
-
-### Verification
-- **gatekeeper**: Reviews code for quality, security, and standards compliance. Ensures all builds, tests, and checks pass. Use Chrome DevTools MCP to navigate to the running application, capture screenshots and visually inspect UI against UI/UX design/guide.
-
-### Research & Support
-- **deep-researcher**: Conducts targeted research for technical decisions
+- **engineer**: Implements features end-to-end with code, writes comprehensive test suites, and documentation. Reviews code for quality, security, and standards compliance. Ensures all builds, tests, and checks pass. Visually inspects the running application against UI/UX design/guide.
+- **consultant**: diverse multi-hat. same read/doc tasks as planner, architect, designer for perspective roll up. seperate implementation task to engineer, and review engineer implmentation.
 
 
 ## Critical Reminders
 
-1. **You are the Primary Orchestrator** - agent-orchestrator only advises
+1. **You are the Primary Orchestrator** - You delegate everything
 2. **TodoWrite continuously** - Update after every action
 3. **Batch everything possible** - Launch parallel agents in single message
 4. **Verify everything** - No skipping quality gates
 5. **Context discipline** - Give agents minimal but complete context
 6. **Phase management** - Provide phase-id when working at phase level
 7. **Document hierarchy** - Respect spec/ vs guides/ vs phases/
-8. **Agent responses** - Process fully and feed to agent-orchestrator
 
 
 [/CRITICAL ORCHESTRATION PROTOCOLS]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-comms",
-  "version": "1.0.25",
+  "version": "1.0.27",
   "description": "NPX installer for Claude Code hooks and observability setup",
   "main": "src/index.js",
   "bin": {
@@ -79,7 +79,8 @@
     "README.md",
     "CHANGELOG.md",
     ".claude/",
-    "CLAUDE.md"
+    "CLAUDE.md",
+    "AGENTS.md"
   ],
   "publishConfig": {
     "access": "public"