@open-code-review/agents 1.1.0 → 1.1.1

package/README.md

@@ -1,35 +1,33 @@
 # @open-code-review/agents
 
-The core skill definitions, reviewer personas, and workflow references for Open Code Review.
+The skill definitions, reviewer personas, and workflow references that power Open Code Review.
 
 ## What This Package Contains
 
-This package provides the AI-readable assets that power multi-agent code review:
-
 ```
 agents/
-├── skills/ocr/           # The OCR skill
-│   ├── SKILL.md          # Tech Lead orchestration logic
+├── skills/ocr/              # The OCR skill
+│   ├── SKILL.md             # Tech Lead orchestration logic
 │   ├── references/
-│   │   ├── workflow.md   # 8-phase review workflow
-│   │   ├── discourse.md  # Multi-agent debate rules
-│   │   ├── synthesis.md  # Finding aggregation guide
-│   │   └── reviewers/    # Persona definitions
-│   │       ├── principal.md
-│   │       ├── quality.md
-│   │       ├── security.md
-│   │       └── testing.md
+│   │   ├── workflow.md      # 8-phase review workflow
+│   │   ├── discourse.md     # Multi-agent debate rules
+│   │   ├── synthesis.md     # Finding aggregation guide
+│   │   └── reviewers/       # Persona definitions (customizable)
+│   │       ├── principal.md # Architecture, design patterns
+│   │       ├── quality.md   # Code style, best practices
+│   │       ├── security.md  # Auth, data handling, vulnerabilities
+│   │       └── testing.md   # Coverage, edge cases
 │   └── assets/
-│       ├── config.yaml   # Default configuration
+│       ├── config.yaml      # Default configuration
 │       └── reviewer-template.md
-├── commands/             # Slash command definitions
+├── commands/                # Slash command definitions
 │   ├── review.md
 │   ├── doctor.md
 │   ├── history.md
 │   ├── show.md
 │   ├── reviewers.md
 │   └── post.md
-└── .claude-plugin/       # Claude Code plugin manifest
+└── .claude-plugin/          # Claude Code plugin manifest
     └── plugin.json
 ```
 
@@ -37,7 +35,7 @@ agents/
 
 ### Via CLI (Recommended)
 
-The CLI copies these assets to your project's `.ocr/` directory and configures your AI tools:
+The CLI copies these assets to your project's `.ocr/` directory:
 
 ```bash
 npx @open-code-review/cli init
@@ -45,46 +43,35 @@ npx @open-code-review/cli init
 
 ### Via Claude Code Plugin
 
-For Claude Code users who prefer plugin-based installation:
-
 ```bash
-# Add the marketplace
 /plugin marketplace add spencermarx/open-code-review
-
-# Install the plugin
-/plugin install open-code-review@spencermarx-open-code-review
-```
-
-### Local Development
-
-Test the plugin locally with Claude Code:
-
-```bash
-claude --plugin-dir ./packages/agents
+/plugin install ocr@aclarify
 ```
 
 ## Skill Architecture
 
-The `skills/ocr/SKILL.md` file defines the **Tech Lead** role—the orchestrator that:
+The `SKILL.md` file defines the **Tech Lead** role—the orchestrator that:
 
 1. Discovers project context (config, OpenSpec, reference files)
 2. Analyzes changes and identifies risk areas
-3. Selects and spawns reviewer personas
+3. Selects and spawns reviewer personas based on your team configuration
 4. Facilitates discourse between reviewers
 5. Synthesizes findings into a unified review
 
-Each reviewer in `references/reviewers/` is a specialized persona with distinct focus areas and anti-patterns to flag.
+Each reviewer in `references/reviewers/` is a specialized persona. You can customize the built-in reviewers or add your own.
 
 ## Commands
 
-| File | CLI Command | Plugin Command |
-|------|-------------|----------------|
-| `review.md` | `/ocr-review` | `/open-code-review:review` |
-| `doctor.md` | `/ocr-doctor` | `/open-code-review:doctor` |
-| `reviewers.md` | `/ocr-reviewers` | `/open-code-review:reviewers` |
-| `history.md` | `/ocr-history` | `/open-code-review:history` |
-| `show.md` | `/ocr-show` | `/open-code-review:show` |
-| `post.md` | `/ocr-post` | `/open-code-review:post` |
+| File | Windsurf | Claude Code / Cursor |
+|------|----------|----------------------|
+| `review.md` | `/ocr-review` | `/ocr:review` |
+| `doctor.md` | `/ocr-doctor` | `/ocr:doctor` |
+| `reviewers.md` | `/ocr-reviewers` | `/ocr:reviewers` |
+| `history.md` | `/ocr-history` | `/ocr:history` |
+| `show.md` | `/ocr-show` | `/ocr:show` |
+| `post.md` | `/ocr-post` | `/ocr:post` |
+
+**Why two formats?** Windsurf requires flat command files with a prefix (`/ocr-command`), while Claude Code and Cursor support subdirectories (`/ocr:command`). Both invoke the same underlying functionality.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-code-review/agents",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "AI-native skills, commands, and reviewer personas for Open Code Review",
   "type": "module",
   "files": [

package/skills/ocr/references/session-state.md

@@ -22,10 +22,10 @@ This means:
 
 ```json
 {
-  "session_id": "2026-01-26-main",
-  "branch": "main",
+  "session_id": "{session-id}",
+  "branch": "{branch-name}",
   "status": "active",
-  "started_at": "2026-01-26T17:00:00Z",
+  "started_at": "{ISO-8601-TIMESTAMP}",
   "current_phase": "reviews",
   "phase_number": 4,
   "completed_phases": ["context", "requirements", "analysis"],
@@ -33,10 +33,12 @@ This means:
     "assigned": ["principal-1", "principal-2", "quality-1", "quality-2"],
     "complete": ["principal-1"]
   },
-  "updated_at": "2026-01-26T17:05:00Z"
+  "updated_at": "{ISO-8601-TIMESTAMP}"
 }
 ```
 
+**IMPORTANT**: Timestamps MUST be generated dynamically using the current time in ISO 8601 format (e.g., `new Date().toISOString()` → `"2026-01-27T09:45:00.000Z"`). Do NOT copy example timestamps.
+
 ## Session Status
 
 The `status` field controls session visibility:
@@ -69,13 +71,41 @@ The Tech Lead MUST update `state.json` at each phase boundary:
 
 ## Writing State
 
-When transitioning phases:
+**CRITICAL**: Always generate timestamps dynamically using the current UTC time in ISO 8601 format.
+
+### Generating Timestamps
 
 ```bash
-# Create or update state.json
-cat > .ocr/sessions/{id}/state.json << 'EOF'
+# macOS/Linux
+date -u +"%Y-%m-%dT%H:%M:%SZ"
+# Output: 2026-01-27T09:45:00Z
+
+# Windows (PowerShell)
+Get-Date -Format "yyyy-MM-ddTHH:mm:ssZ" -AsUTC
+
+# Node.js / JavaScript
+new Date().toISOString()
+```
+
+When creating a new session (Phase 1 start):
+
+```json
 {
-  "session_id": "{id}",
+  "session_id": "{session-id}",
+  "status": "active",
+  "current_phase": "context",
+  "phase_number": 1,
+  "completed_phases": [],
+  "started_at": "{CURRENT_ISO_TIMESTAMP}",
+  "updated_at": "{CURRENT_ISO_TIMESTAMP}"
+}
+```
+
+When transitioning phases (preserve `started_at`, update `updated_at`):
+
+```json
+{
+  "session_id": "{session-id}",
   "status": "active",
   "current_phase": "reviews",
   "phase_number": 4,
@@ -84,25 +114,23 @@ cat > .ocr/sessions/{id}/state.json << 'EOF'
     "assigned": ["principal-1", "principal-2", "quality-1", "quality-2"],
     "complete": []
   },
-  "updated_at": "2026-01-26T17:05:00Z"
+  "started_at": "{PRESERVE_ORIGINAL}",
+  "updated_at": "{CURRENT_ISO_TIMESTAMP}"
 }
-EOF
 ```
 
 When closing a session (Phase 8 complete):
 
-```bash
-# Update state.json to close the session
-cat > .ocr/sessions/{id}/state.json << 'EOF'
+```json
 {
-  "session_id": "{id}",
+  "session_id": "{session-id}",
   "status": "closed",
   "current_phase": "complete",
   "phase_number": 8,
   "completed_phases": ["context", "requirements", "analysis", "reviews", "aggregation", "discourse", "synthesis"],
-  "updated_at": "2026-01-26T17:30:00Z"
+  "started_at": "{PRESERVE_ORIGINAL}",
+  "updated_at": "{CURRENT_ISO_TIMESTAMP}"
 }
-EOF
 ```
 
 ## Benefits

package/skills/ocr/references/workflow.md

@@ -73,11 +73,13 @@ At **every phase transition**, update `.ocr/sessions/{id}/state.json`:
   "current_phase": "reviews",
   "phase_number": 4,
   "completed_phases": ["context", "requirements", "analysis"],
-  "started_at": "2026-01-26T17:00:00Z",
-  "updated_at": "2026-01-26T17:05:00Z"
+  "started_at": "{PRESERVE_ORIGINAL}",
+  "updated_at": "{CURRENT_ISO_TIMESTAMP}"
 }
 ```
 
+**CRITICAL**: Generate timestamps dynamically (e.g., `date -u +"%Y-%m-%dT%H:%M:%SZ"` on macOS/Linux). Preserve `started_at` from session creation; always update `updated_at` with current time.
+
 **Status values**: `active` (in progress), `closed` (complete and dismissed)
 
 **Phase values**: `context`, `requirements`, `analysis`, `reviews`, `aggregation`, `discourse`, `synthesis`, `complete`