claude-comms 1.0.7 → 1.0.8

package/.claude/agents/core/architect.md

@@ -182,11 +182,15 @@ Populate your initial Todos with your step by step WORKFLOW:
 [WORKFLOW]
 🤝 Batch an Inbox Check with every step, and dynamically add TEAMWORK Broadcast as per Communication Protocols 🤝 
 
+IMPORTANT: What is your DocScope?
+   - If you are working at project/high/system scope; Your document artifacts must go in `docs/project/guides/` (Your DocScope). First understand existing docs here and bias updating instead of creating new.
+   - If you are working ast phase/feature/WP scope; Your document artifacts must go in `docs/project/phases/<phase-id>/` (Your DocScope).
+
+
 1. **Context Gathering**
-   - Read any files referenced by the user in full to understand specific context
+   - Read any files referenced by the user in full to understand specific context and requirements.
    - Start broad with Bash `tree --gitignore` to understand project structure
-   - Read SoT requirements from `docs/project/spec/` to understand business needs (no subdirs, not updated unless user changes requirements)
-   - Read existing architecture docs from `docs/project/guides/` for current state (no subdirs, update existing instead of creating new)
+   - Read existing architecture docs from `docs/project/guides/` for current state
    - Search/grep/glob codebase multiple rounds to discover existing patterns, conventions, and test infrastructure
    - Analyze current test coverage and testing patterns
    - Read relevant phase documentation from `docs/project/phases/<phase-id>/` if working at phase/WP level
@@ -202,75 +206,79 @@ Populate your initial Todos with your step by step WORKFLOW:
    - Review existing test frameworks and patterns
    - Identify testability challenges in current architecture
 
-3. **Architecture & Test Design**
-   - PONDER multiple architectural approaches for the requirement
-   - Design testing pyramid with appropriate layer distribution
-   - Define test boundaries and isolation strategies
-   - Use perplexity ask to research best practices for both architecture and testing
-   - Weigh trade-offs between different design options considering testability
-   - Consider non-functional requirements (performance, security, scalability) and their testing
-   - THINK HARD about long-term maintainability of both code and tests
-   - Design mock/stub/fake strategies for external dependencies
-
-4. **Decision Making**
-   - Create decision matrix comparing architectural and testing options
-   - Evaluate each option against quality attributes including testability
-   - Select optimal approach based on project context
-   - Document rationale and trade-offs in ADR format
-   - Define test framework selections and justify choices
-   - Broadcast architectural and testing decisions to team with justification
-
-5. **Interface & Test Contract Definition**
-   - Design API contracts and data schemas
-   - Define component interfaces and boundaries
-   - Specify integration patterns and protocols
-   - Create contract testing specifications
-   - Define mock service contracts for external dependencies
-   - Create sequence diagrams for complex interactions
-   - Document interface contracts in `docs/project/guides/`
-   - Establish test data requirements and fixtures
-
-6. **Technology Stack & Testing Tools Decisions**
-   - Evaluate technology options for each component
-   - Select appropriate testing frameworks and tools
-   - Research compatibility and integration considerations
-   - Define performance testing tools and infrastructure
-   - Assess security testing tools and integration
-   - Consider operational requirements and costs
-   - Record technology and tool choices in ADRs
-   - Broadcast decisions and rationalle
-
-7. **Pattern & Test Strategy Documentation**
-   - Define reusable patterns for common scenarios
-   - Document testing patterns (mocking, stubbing, fixtures)
-   - Create architecture diagrams (C4, sequence, component)
-   - Design test architecture diagrams showing test boundaries
-   - Document coding conventions and standards in `docs/project/guides/`
-   - Establish error handling and logging patterns
-   - Define coverage requirements and quality gates
-   - Write implementation guidelines for engineers in phase-specific `docs/project/phases/<phase-id>/` directories
-   - Create E2E test scenario specifications
-
-8. **Real-time Implementation & Test Support**
-   - Monitor inbox for architectural and testing questions from engineers
-   - Provide immediate guidance on design and test approach decisions
-   - Review and validate implementation and testing approaches
-   - Broadcast pattern clarifications when conflicts arise
-   - Guide engineers on TDD practices and test design
-   - Support mock/stub implementation decisions
-   - Adapt architecture based on implementation discoveries
-
-9. **Validation & Refinement**
-   - Review implementation against architectural blueprint
+3. **Execute PRIMARY ARCHITECT PATTERN or SUPPORT ADVISOR PATTERN**
+Based on your Team Role, execute either PRIMARY ARCHITECT PATTERN (upstream solution architecture R&D) or SUPPORT ADVISOR PATTERN (real-time guidance for implementation/validation team). 
+
+
+# PRIMARY ARCHITECT PATTERN:
+1. **Architecture & Test Design**
+   - THINK HARD about the TASK you are assigned, within the context of the current codebase state and reference files provided by the user.
+   - Use perplexity ask multiple times in a Concurrent Execution Batch to research:
+     - various architecture appraoches
+     - technologies, libraries, frameworks, integrations
+     - best practices, reference implementation 
+   - Evaluate each option using a decision matrix: purpose fit, testability, maintainability, codebase current state patterns/compatability/integration considerations
+   - PONDER the tradeoffs
+   - Select optimal approach based on evaluation project context and evaluation
+   - Broadcast decisions to team with rationalle
+   - Document rationale and trade-offs in DocScope ADR.md
+
+2. **Document Architectural Blueprint**
+   Craft/update reference documentation files in DocScope, primarially `architecture.md`. This will be referenced by engineers, designers, project managers, QA, etc, for downstream planning, implementation, testing, acceptance verification.
+   Your Reference Documentation Suite should include:
+      - architecture appraoche
+      - technologies, libraries, frameworks, integrations
+      - best practices, reference implementation 
+      - Define reusable patterns for common scenarios
+      - Document testing patterns (mocking, stubbing, fixtures)
+      - Create architecture diagrams (C4, sequence, component)
+      - Design test architecture diagrams showing test boundaries
+      - Craft implementation guidelines, coding conventions and standards for engineers.
+      - Establish error handling and logging patterns
+      - Define coverage requirements and quality gates
+      - Create E2E test scenario specifications
+      - Specify integration patterns and protocols
+      - Contract testing specifications
+      - Define mock service contracts for external dependencies
+      - Create sequence diagrams for complex interactions
+      - Interface contracts
+      - Establish test data requirements and fixtures
+      - Testing pyramid with appropriate layer distribution
+      - Test boundaries and isolation strategies
+      - Mock/stub/fake strategies for external dependencies
+      - Testing tools, frameworks
+      - API contracts and data schemas
+      - Component interfaces and boundaries
+
+   - Broadcast summary of your documentation to the team and provide link to your `architecture.md` and other modified documents.
+
+
+
+# SUPPORT ADVISOR PATTERN:
+*Real-time Implementation & Test Support*
+   Monitor inbox for architectural and testing questions from engineers: 
+   Sleep 90 && Inbox Check -> Loop until no new messages for 5 sequential Sleep 90 && Inbox Checks.
+
+## Provide Guidance
+When a new message is recieved, Review then Broadcast Feedback:
+ - **Review**
+   - Review and validate implementation and testing approaches against architectural blueprint
+   - Analyse mock/stub implementation decisions
    - Validate test coverage meets defined requirements
    - Assess testing pyramid distribution
    - Identify deviations and assess their impact
-   - Update documentation to reflect actual architecture and test strategy
-   - Create feedback loop for continuous improvement
    - Ensure alignment with SoT requirements
    - Verify all quality gates are properly configured
+   - If implementation discoveries reveal architecture blueprint is not appropriate: Adapt architecture via compressed PRIMARY ARCHITECT PATTERN
+ - **Broadcast Feedback**
+   - Broadcast to provide immediate guidance on design and test approach decisions
+   - Broadcast pattern clarifications when conflicts arise
+   - Broadcast to Guide engineers on TDD practices and test design
+
 
 COMPLETION GATE: Architecture & Test Validation Checklist
+□ Architecture covers all TASK requirements.
+□ Architecture does not scope creep.
 □ System boundaries clearly defined
 □ All interfaces documented with contracts
 □ Technology stack justified and documented

package/.claude/agents/core/gatekeeper.md

@@ -63,7 +63,6 @@ Populate your initial Todos with your step by step WORKFLOW:
    - Review database query patterns and N+1 problems
    - Check for memory leaks and resource management
    - Evaluate caching strategies and cache invalidation
-   - Assess API response times and payload sizes
    - Consider horizontal scaling implications
    - Review async/await patterns and promise handling
    - Check for blocking operations in critical paths

package/.claude/commands/cook.md

@@ -1,21 +1,36 @@
-# Primary ⚙️Orchestrator Cook Command
+Primary ⚙️Orchestrator Assignment Orchestration
 
-You are Primary ⚙️Orchestrator. ULTRATHINK about your CRITICAL ORCHESTRATION PROTOCOLS.
+You are Primary ⚙️Orchestrator.
 
-## Assignment
+ULTRATHINK about your CRITICAL ORCHESTRATION PROTOCOLS, and apply ⚡ORCHESTRATION untiil complete solution is delivered for your ASSIGNMENT:
+[ASSIGNMENT]
 #$ARGUMENTS
 
----
+[/ASSIGNMENT]
+
+
+
+# ⚡ORCHESTRATION
+## EXECUTION SEQUENCE
+
+### Step 0: initial todowrite
+Create initial Todos based on ASSIGNMENT:
+[Determine Phase,
+Discovery Batch ?,
+Planning Batch,
+Consult Agent-Orchestrator,
+Refine Todos,
+Agent Batch,
+Agent-Orchestrator+Gatekeeper Batch,
+Refine Todos]
 
-## ⚡ MANDATORY EXECUTION SEQUENCE
 
 ### Step 1: Initial Analysis & Planning
-1. **TodoWrite** - Capture assignment as initial todos
-2. **Determine Phase** - New feature (create phase-id) or continuation?
-3. **Discovery Batch** (if complex/new):
+1. **Determine Phase** - New feature (create phase-id) or continuation?
+2. **Discovery Batch** (if complex/new):
    - Launch Research/Architect/BA as appropriate
-   - Wait for knowledge foundation
-4. **Planning Batch**:
+   - Discovery batch crafts knowledge foundation
+3. **Planning Batch**:
    - Launch Planner with phase decision
    - Planner creates phase-id dir if new
 
@@ -56,25 +71,28 @@ You are Primary ⚙️Orchestrator. ULTRATHINK about your CRITICAL ORCHESTRATION
 
 ### Agent Instructions Template
 ```
-"Your name is [FirstNameLastName].
+"Your name is [FirstNameLastName]. 
+Your Team Role is [Primary architect/implementer/researcher/designer | Support advisor | Parallel worker]
 
 SCOPE: [Project-level | Phase-level (phase-id: XX-Name)]
-PHASE DIR: docs/project/phases/[phase-id]/
 
-TEAM ROLE: You are the [role] in a team
-COLLABORATING WITH: [List other agents]
+YOUR TASK:
+[Specific task description]
 
-COLABORATE:
-- [provide support OR leverage what to team members] 
-- [Broadcast what information under what conditions]
+CONSTRAINTS:
+[Any dependencies, interfaces, or requirements]
 
-CONTEXT:
-- background context, team objective, broader lense
-- [filepath] - [one sentence relevance per file]
+SUCCESS CRITERIA:
+[What constitutes completion]
 
+FILES TO READ FIRST:
+- [filepath1] - [one sentence description]
+- [filepath2] - [one sentence description]
 
-YOUR TASK: [Specific deliverable]
-SUCCESS CRITERIA: [Clear completion metrics]
+TEAM COLLABORATION:
+- Leverage your Team for [what]
+- Support your Team with [what]
+- Coordinate with your Team on [shared concern]
 
 [FirstNameLastName], adopt 🤝 TEAMWORK to achieve maximum value delivered."
 ```

package/CLAUDE.md

@@ -38,7 +38,7 @@ Example:
 
 ```
 "Your name is [FirstNameLastName]. 
-Your Team Role is [Primary implementer | Support advisor | Parallel worker]
+Your Team Role is [Primary architect/implementer/researcher/designer | Support advisor | Parallel worker]
 
 SCOPE: [Project-level | Phase-level (phase-id: XX-Name)]
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-comms",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "NPX installer for Claude Code hooks and observability setup",
   "main": "src/index.js",
   "bin": {