fix(docs): resolve 8 technical accuracy issues across examples and README

Fix OPA/Cedar mixing, ARN regex, authority hierarchy, sizing
contradiction, broken anchor links, DELIVERY_RULES references,
git worktree args, nested asyncio.run(), and Mermaid diagram
contradictions.

Author: PaulDuvall

README.md

@@ -107,23 +107,22 @@ graph TD
 
     subgraph "Phase 2: Development (Weeks 3-4)"
         D --> G[Spec-Driven Development]
-        D --> H[Planned Implementation]
-        G --> I[Progressive Enhancement]
-        H --> I
+        H[Planned Implementation]
+        I[Progressive Enhancement]
         I --> J[Choice Generation]
         Q[Event Automation]
         R[Custom Commands]
         S[Progressive Disclosure]
         U[Image Spec]
-        G --> K[Atomic Decomposition]
+        I --> K[Atomic Decomposition]
         K --> L[Parallel Agents]
     end
 
     subgraph "Phase 3: Operations (Weeks 5-6)"
         C --> M[Policy Generation]
         M --> N[Security Orchestration]
         N --> T[Centralized Rules]
-        L --> O[Baseline Management]
+        F --> O[Baseline Management]
         D --> P[Automated Traceability]
     end
 
@@ -446,7 +445,7 @@ Each developer maintains their own prompts and preferences, leading to inconsist
 **Maturity**: Beginner
 **Description**: Run AI tools in isolated environments without access to secrets or sensitive data to prevent credential leaks and maintain security compliance.
 
-**Related Patterns**: [Security & Compliance Patterns](#security-compliance-patterns), [Codified Rules](#codified-rules), [Event Automation](#event-automation)
+**Related Patterns**: [Security & Compliance Patterns](#security--compliance-patterns), [Codified Rules](#codified-rules), [Event Automation](#event-automation)
 
 **Core Security Implementation**
 
@@ -693,7 +692,7 @@ graph TD
 
 **Core Principles**
 
-- **Small Batch Sizing**: Each work item sized for <1 hour (AI-assisted development velocity) to enable continuous delivery and rapid feedback
+- **Small Batch Sizing**: Each work item sized for 4-8 hours max to enable continuous delivery and rapid feedback
 - **AI-Assisted Decomposition**: Use AI to break down requirements into implementable tasks
 - **Traceability Integration**: Connect issues to implementation files and CI workflows
 - **Dependency Mapping**: Establish clear relationships between work items and epics
@@ -1246,7 +1245,9 @@ for branch in $(git branch -r | grep 'agent/'); do
 done
 
 # Cleanup
-git worktree remove ../agent-auth ../agent-api ../agent-tests
+git worktree remove ../agent-auth
+git worktree remove ../agent-api
+git worktree remove ../agent-tests
 ```
 
 **Shared Memory & Coordination**
@@ -2204,7 +2205,7 @@ graph TD
 
 ```bash
 # Create comprehensive error context file
-cat > .error-context.md << 'EOF'
+cat > .error-context.md << EOF
 # Error Analysis
 
 **Error Output:**
@@ -2427,8 +2428,8 @@ Operations patterns focus on CI/CD, security, compliance, and production managem
 ai "Convert compliance requirements into Cedar policy code:
 SOC 2: Data at rest must be AES-256 encrypted" > encryption.cedar
 
-# Test generated policies
-opa test encryption.cedar
+# Validate generated Cedar policies
+cedar validate --schema schema.cedarschema encryption.cedar
 ```
 
 **Complete Implementation**: See [examples/policy-generation/](examples/policy-generation/) for:
@@ -2611,9 +2612,9 @@ Manual thresholds quickly become stale, causing alert storms or blind spots.
 4. **[Atomic Decomposition](#atomic-decomposition)** - Break down complex features
 
 ### Phase 3: Operations (Weeks 5-6)
-1. **[Security & Compliance Patterns](#security-compliance-patterns)** - Implement unified security framework
+1. **[Security & Compliance Patterns](#security--compliance-patterns)** - Implement unified security framework
 2. **[Deployment Automation Patterns](#deployment-automation-patterns)** - Establish AI-powered CI/CD
-3. **[Monitoring & Maintenance Patterns](#monitoring-maintenance-patterns)** - Deploy proactive system management
+3. **[Monitoring & Maintenance Patterns](#monitoring--maintenance-patterns)** - Deploy proactive system management
 
 **Note**: For teams practicing continuous delivery, implement security ([Security Sandbox](#security-sandbox), AI Security & Compliance) and deployment patterns (Deployment Automation) from week 1 alongside foundation patterns. The phases represent learning dependencies, not deployment sequences.
 

docs/claude-code-guide.md

@@ -609,29 +609,25 @@ workflows:
 
 **1. Automated Code Review**
 ```bash
-# .claude/hooks/pre-commit
-claude review --files "$(git diff --cached --name-only)" \
-  --checklist ".claude/review-checklist.md" \
-  --output "review-report.md"
+# Use single-prompt mode in a pre-commit hook or CI step
+claude -p "Review the staged changes for bugs, security issues, and style \
+  violations. Check against the guidelines in .claude/review-checklist.md. \
+  Output a summary of findings." --output-file review-report.md
 ```
 
 **2. Documentation Generation**
 ```bash
-# Generate comprehensive docs
-claude document \
-  --source "src/**/*.ts" \
-  --format "markdown" \
-  --include-examples \
-  --output "docs/api/"
+# Generate docs using single-prompt mode
+claude -p "Generate comprehensive API documentation in markdown for all \
+  exported functions in src/**/*.ts. Include usage examples. \
+  Write the output to docs/api/."
 ```
 
 **3. Test Generation**
 ```bash
-# Generate tests for new code
-claude generate-tests \
-  --target "src/services/newFeature.ts" \
-  --coverage-target 90 \
-  --include-edge-cases
+# Generate tests using single-prompt mode
+claude -p "Generate tests for src/services/newFeature.ts targeting 90% \
+  coverage. Include edge cases for error handling and boundary conditions."
 ```
 
 ### Building Autonomous Agents

examples/codified-rules/CLAUDE.md

@@ -35,7 +35,7 @@ Build a simple, reliable subscription reminder system that helps users avoid une
 - **VALIDATE** all AI-generated code
 - **MAINTAIN** .ai/ configuration directory with standards
 
-### 3. DELIVERY_RULES.md - CI/CD Pipeline & Deployment
+### 3. PIPELINE_RULES.md - CI/CD Pipeline & Deployment
 - **ENFORCE** branch age < 2 days
 - **REQUIRE** build time < 10 minutes
 - **VALIDATE** all AI output through security gates
@@ -90,7 +90,7 @@ Per QUALITY_RULES.md requirements:
    ```
 
 ### Pipeline Requirements
-Per DELIVERY_RULES.md requirements:
+Per PIPELINE_RULES.md requirements:
 1. **Version Control**: All configs, specs, and IaC in Git
 2. **Testing Pyramid**: 70% unit, 20% integration, 10% E2E
 3. **Deployment Safety**: Feature flags for gradual rollout
@@ -130,14 +130,14 @@ Per DELIVERY_RULES.md requirements:
    - Follow SOLID principles
    - Include traceability comments
 
-4. **VALIDATE LOCALLY** (DELIVERY_RULES.md)
+4. **VALIDATE LOCALLY** (PIPELINE_RULES.md)
    ```bash
    pytest tests/ --cov=src --cov-fail-under=90
    ./check_traceability.sh
    pre-commit run --all-files
    ```
 
-5. **DEPLOY SAFELY** (DELIVERY_RULES.md)
+5. **DEPLOY SAFELY** (PIPELINE_RULES.md)
    - Complete ORR checklist
    - Use feature flags
    - Monitor rollout
@@ -221,7 +221,7 @@ subscription-alerts/
 ├── docs/
 │   ├── DEVELOPMENT_RULES.md      # Test-first practices
 │   ├── QUALITY_RULES.md          # Code standards
-│   └── DELIVERY_RULES.md         # CI/CD requirements
+│   └── PIPELINE_RULES.md         # CI/CD requirements
 └── run_tests.sh                   # Local = CI
 ```
 
@@ -305,7 +305,7 @@ When reviewing or implementing code:
    - SOLID principles followed?
    - Logging structured?
 
-3. **THIRD**: Check DELIVERY_RULES.md
+3. **THIRD**: Check PIPELINE_RULES.md
    - Branch < 2 days old?
    - Build < 10 minutes?
    - ORR complete?
@@ -319,6 +319,6 @@ If ANY check fails, STOP and report the violation.
 **The three rules are LAW:**
 - DEVELOPMENT_RULES.md = How we write (test-first, traceable)
 - QUALITY_RULES.md = What we write (clean, observable)
-- DELIVERY_RULES.md = How we ship (safe, automated)
+- PIPELINE_RULES.md = How we ship (safe, automated)
 
 **Every code change must comply with ALL THREE rule files. No exceptions.**

examples/codified-rules/PIPELINE_RULES.md

@@ -1,4 +1,4 @@
-# DELIVERY_RULES - CI/CD Pipeline & Deployment Excellence
+# PIPELINE_RULES - CI/CD Pipeline & Deployment Excellence
 
 **CRITICAL: Review these rules before EVERY change to code, pipeline, or infrastructure. Non-negotiable requirements for continuous delivery.**
 

examples/developer-lifecycle/comprehensive-workflow-example.md

@@ -318,23 +318,26 @@ Generate monitoring dashboard configuration for authentication metrics."
 
 ### Claude Code
 ```bash
-# Use Plan Mode for initial planning
-claude plan "Implement JWT authentication for SaaS application"
-
-# Use implementation mode for function development
-claude implement "Generate JWT service following OpenAPI specification"
-
-# Use review mode for integration testing
-claude review "Validate complete authentication flow implementation"
+# Start interactive session and enter plan mode
+claude
+# Then in the session:
+#   > /plan
+#   > "Design JWT authentication for SaaS application"
+#   > /exitplan
+#   > "Implement the JWT service following the OpenAPI specification"
+#   > "Review and validate the complete authentication flow"
+
+# Or use single-prompt mode for scripted workflows
+claude -p "Generate JWT service following OpenAPI specification"
 ```
 
 ### Cursor
 ```bash
-# Use /plan command for structured planning
-/plan JWT authentication implementation with security requirements
+# Use Cmd+L chat with @codebase for planning context
+# "Plan JWT authentication implementation with security requirements" @codebase
 
-# Use @codebase for implementation with context
-/implement JWT service @codebase following test specifications
+# Use Cmd+K inline edit to implement with file context
+# "Implement JWT service following test specifications" @file:auth.test.ts
 
 # Use /fix for handling implementation issues
 /fix authentication endpoint failing test cases

examples/developer-lifecycle/enhanced-implementation-techniques.md

@@ -367,32 +367,42 @@ ai "Break registration validation into individual functions:
 
 ### Claude Code Enhanced Workflow
 ```bash
-# Use Plan Mode for comprehensive planning
-claude plan "Implement comprehensive user authentication with JWT, session migration, and mobile support"
-
-# Use enhanced context in implementation mode
-claude implement "JWT authentication service" --context="existing session system, PostgreSQL users table, mobile app requirements"
-
-# Apply Five-Try Rule systematically
-claude retry "authentication implementation" --attempt=3 --previous-failures="token validation errors, session migration issues"
-
-# Use review mode for integration validation
-claude review "complete authentication flow" --focus="security, performance, integration points"
+# Start interactive session with plan mode for comprehensive planning
+claude
+# Then in the session:
+#   > /plan
+#   > "Implement comprehensive user authentication with JWT, session migration,
+#      and mobile support. Consider existing session system, PostgreSQL users
+#      table, and mobile app requirements."
+#   > /exitplan
+
+# Implement with context — reference relevant files directly
+#   > "Implement JWT authentication service. See src/auth/ for the existing
+#      session system and db/schema.sql for the users table."
+
+# Apply Five-Try Rule — provide failure context in follow-up prompts
+#   > "The token validation is failing with [error]. Previous attempts had
+#      session migration issues. Try a different approach."
+
+# Review the implementation
+#   > "Review the complete authentication flow for security, performance,
+#      and integration concerns."
 ```
 
 ### Cursor Enhanced Workflow
 ```bash
-# Use /plan with comprehensive context
-/plan JWT authentication implementation @codebase @docs considering existing session system and mobile requirements
+# Use Cmd+L chat with comprehensive context references
+# "Implement JWT authentication considering existing session system and mobile
+#  requirements" @codebase @docs
 
-# Enhanced implementation with context
-/implement JWT service @existing-auth @session-middleware following test specifications
+# Use Cmd+K inline edit with specific file context
+# "Implement JWT service following test specifications" @file:auth.test.ts @file:session.ts
 
-# Systematic retry with context
-/fix authentication issues @previous-attempts considering alternative approaches
+# Use /fix with context for systematic retry
+/fix authentication issues @codebase
 
-# Integration validation
-/validate complete auth flow @tests @integration ensuring security and performance standards
+# Review integration with Cmd+L chat
+# "Review complete auth flow for security and performance standards" @codebase
 ```
 
 ## Success Metrics and Validation

examples/parallel-agents/README.md

@@ -293,7 +293,10 @@ def main(task_file: str, task_id: str):
     agent = AIAgent(agent_id, task_id)
     
     # Run the task
-    asyncio.run(agent.execute_task(asyncio.run(agent.load_task(task_file))))
+    async def run():
+        task = await agent.load_task(task_file)
+        await agent.execute_task(task)
+    asyncio.run(run())
 
 if __name__ == "__main__":
     main()

examples/planned-implementation/cursor-example.md

@@ -1,23 +1,25 @@
 # Cursor Planning Example
 
-This example demonstrates how to use Cursor's `/plan` command and planning features to implement a React component library.
+This example demonstrates how to use Cursor's Composer and Chat features to plan and implement a React component library.
 
 ## Scenario
 Building a reusable design system component library for a React application with TypeScript, Storybook, and automated testing.
 
-## Step 1: Using Cursor's /plan Command
+## Step 1: Using Cursor's Composer for Planning
 
-Open Cursor's chat and use the `/plan` command:
+Open Cursor's Composer (Cmd+I / Ctrl+I) and describe the project:
 
 ```
-/plan Create a React component library with the following requirements:
+Create a React component library with the following requirements:
 - TypeScript support with strict typing
 - Storybook for component documentation
 - Jest testing with React Testing Library
 - CSS-in-JS with styled-components
 - Rollup for bundling
 - Publishing to npm
 - Components: Button, Input, Modal, Card
+
+Start by creating an implementation plan before writing any code.
 ```
 
 ## Step 2: Cursor Generated Plan
@@ -80,7 +82,7 @@ src/
 
 ## Step 3: Interactive Plan Refinement
 
-Use Cursor's iterative planning approach:
+Use Cursor's chat (Cmd+L / Ctrl+L) to iterate on the plan:
 
 ```
 This plan looks great! Can you expand the theming section? I need:
@@ -114,7 +116,7 @@ Also, add ESLint and Prettier configuration to Phase 1.
 
 ## Step 4: Execute with Cursor
 
-Start implementation with plan reference:
+Start implementation using the Composer with plan reference:
 
 ```
 Let's start with Phase 1. Begin by creating the package.json and TypeScript configuration according to our plan.
@@ -138,18 +140,18 @@ export const Button = styled.button<ButtonProps>`
 
 ## Benefits Demonstrated
 
-1. **Modular Planning**: Cursor's `/plan` breaks work into logical phases
+1. **Structured Planning**: Composer breaks work into logical phases
 2. **Interactive Refinement**: Easy to modify plan based on new requirements
 3. **Contextual Implementation**: Code generation follows plan structure
 4. **Progress Visibility**: Clear tracking of implementation status
 5. **Team Alignment**: Shareable plan format for collaboration
 
 ## Cursor-Specific Features Used
 
-- **`/plan` command**: Generates structured implementation roadmap
-- **Interactive chat**: Allows plan iteration and refinement
-- **Context awareness**: Understands existing project structure
-- **Code generation**: Implements following plan specifications
-- **Inline comments**: Tracks progress against plan
+- **Composer (Cmd+I)**: Multi-file code generation following plan specifications
+- **Chat (Cmd+L)**: Plan iteration, refinement, and asking questions with @codebase context
+- **@codebase / @file references**: Provides context awareness of existing project structure
+- **Inline edits (Cmd+K)**: Targeted code changes within plan specifications
+- **`/fix` command**: Addresses failing tests during implementation
 
 This example demonstrates how Cursor's planning features create a structured approach to complex component library development.