trinity-method-sdk 2.2.1 → 2.2.2

package/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.2.2] - 2026-02-25
+
+### Changed
+
+- **Simplified gitignore patterns** - Deploy and update commands now add `.claude/` and
+  `*CLAUDE.md` to `.gitignore` instead of granular `.claude/trinity/archive/` and
+  `.claude/trinity/templates/` patterns. Migration handles cleanup of old patterns. (Issue #18)
+
+### Fixed
+
+- **Work order numbering scans archive directory** - Added explicit WO numbering instructions to
+  `/utility:trinity-workorder` template. Numbers now derived only from `work-orders/` and
+  `sessions/` directories, ignoring archives. New sessions start fresh at WO-001. (Issue #19)
+- **trinity-end command not archiving all session files** - Updated STRICT ARCHIVING PROTOCOL
+  in `/session:trinity-end` template to archive from all `.claude/trinity/` subdirectories
+  (Issue #17)
+  - Added archiving of completed work orders from `work-orders/` directory
+  - Added archiving of completed investigations and plans from `investigations/` directory
+  - Added archiving of Claude Code plan mode files from `plans/` directory
+  - Added loose archive file organization into YYYY-MM-DD date folders
+  - Expanded clean slate verification to cover `plans/` directory
+
 ## [2.2.1] - 2026-02-24
 
 ### Added

package/README.md

@@ -1,550 +1,550 @@
-# Trinity Method SDK
-
-[![npm version](https://img.shields.io/npm/v/trinity-method-sdk?color=success)](https://www.npmjs.com/package/trinity-method-sdk)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Node.js Version](https://img.shields.io/badge/node-%3E%3D16.9.0-brightgreen)](https://nodejs.org/)
-[![AI Agents](https://img.shields.io/badge/AI%20Agent-Claude%20Code-blue)](https://github.com/lukadfagundes/trinity-method-sdk)
-
-> Investigation-first development methodology for Claude Code
-
----
-
-## Why Trinity Method Exists
-
-### The Problem with Traditional AI-Assisted Development
-
-AI coding assistants are powerful, but without structure they become expensive guessing machines:
-
-**❌ Jump-to-Code Anti-Pattern:**
-
-- AI generates code without understanding the problem
-- No investigation phase → immediate implementation
-- Context lost between sessions → repeated mistakes
-- No institutional knowledge → every session starts from zero
-- Inconsistent quality → success depends on prompt luck
-- Manual quality setup → 50 minutes configuring linters per project
-
-**The Cost:**
-
-- Developers waste time debugging AI-generated code that solves the wrong problem
-- Teams lose hard-won lessons when developers leave
-- Technical debt accumulates invisibly
-- Code quality varies wildly across sessions
-
-### Our Philosophy: Investigation-First Development
-
-Trinity Method rejects "prompt and pray" development. Instead, we enforce **systematic investigation before implementation**:
-
-#### 1. Investigation-First Principle
-
-```text
-WRONG: "Build authentication" → AI generates code → Debug for hours
-RIGHT: "Investigate authentication requirements" → Understand problem → Design solution → Implement correctly
-```
-
-#### 2. Evidence-Based Decisions
-
-Every decision backed by documentation, codebase metrics, and historical patterns. No guessing.
-
-**3. Knowledge Preservation**
-Lessons learned persist across sessions through institutional memory. Agents get smarter over time.
-
-**4. Systematic Quality Assurance**
-Quality isn't aspirational—it's systematically enforced through automated gates (BAS 6-phase validation).
-
-### The Trinity Transformation
-
-**✅ With Trinity Method:**
-
-- **Investigation before coding** → Understand the problem first
-- **Persistent knowledge base** → Learn from every session
-- **Automated quality enforcement** → BAS gates ensure standards
-- **18-agent team coordination** → Right specialist for each task
-- **Institutional memory** → Patterns, strategies, and lessons preserved
-- **90-second deployment** → Complete development environment instantly
-
----
-
-## What is Trinity Method SDK
-
-Trinity Method SDK is a **production-ready development methodology** that transforms AI-assisted coding
-from random generation into systematic engineering.
-
-### Core Philosophy
-
-**Trinity Method enforces three pillars:**
-
-1. **Investigation-First Development**
-   - Systematic investigation using MON (Requirements), ROR (Design), TRA (Planning)
-   - Evidence-based decisions backed by documentation and metrics
-   - Scale-based workflows: SMALL (0 stop points) → MEDIUM (2 stop points) → LARGE (4 stop points)
-
-2. **Knowledge Preservation**
-   - Learning system captures patterns from every investigation
-   - Cross-session persistence through filesystem storage
-   - Agent knowledge sharing via pub/sub bus (≥0.8 confidence threshold)
-
-3. **Systematic Quality Assurance**
-   - BAS 6-phase quality gate: Lint → Structure → Build → Test → Coverage (≥80%) → Review
-   - Crisis management system for 5 crisis types (build, test, error, performance, security)
-   - Automated codebase metrics collection and technical debt tracking
-
-### The 18-Agent Team
-
-Trinity SDK includes **18 specialized agents** organized across 5 functional teams:
-
-**Planning Layer:**
-
-- **MON** - Requirements Analyst (functional & non-functional requirements)
-- **ROR** - Design Architect (technical design, ADRs)
-- **TRA** - Work Planner (implementation sequencing, BAS integration)
-- **EUS** - Task Decomposer (atomic task breakdown)
-
-**Execution Layer:**
-
-- **KIL** - Task Executor (TDD implementation: RED → GREEN → REFACTOR)
-- **BAS** - Quality Gate (6-phase validation enforcer)
-- **DRA** - Code Reviewer (design doc compliance, quality escalation)
-
-**Support Layer:**
-
-- **APO** - Documentation Specialist (API docs, inline comments)
-- **BON** - Dependency Manager (package security, version management)
-- **CAP** - Configuration Specialist (env vars, config files)
-- **URO** - Refactoring Specialist (technical debt reduction)
-
-**Leadership:**
-
-- **ALY** - Chief Technology Officer (investigation orchestration, strategic coordination)
-- **AJ MAESTRO** - Orchestrator (multi-agent workflow orchestration, task delegation)
-
-**Deployment:**
-
-- **TAN** - Structure Specialist (directory structure validation)
-- **ZEN** - Knowledge Base Specialist (comprehensive documentation)
-- **INO** - Context Specialist (CLAUDE.md hierarchy management)
-- **EIN** - CI/CD Specialist (continuous integration/deployment automation)
-
-**Audit:**
-
-- **JUNO** - Quality Auditor (comprehensive codebase audits, deployment verification)
-
-### What Gets Deployed
-
-Trinity deploys **88 production-ready components** in 90 seconds:
-
-**Methodology Infrastructure:**
-
-- `.claude/trinity/knowledge-base/` - 9 living documentation files
-  - ARCHITECTURE.md (codebase metrics, architecture documentation)
-  - ISSUES.md (known issues and bug tracking)
-  - To-do.md (task management and priorities)
-  - Technical-Debt.md (technical debt tracking)
-  - Trinity.md (project-specific Trinity guide)
-  - TESTING-PRINCIPLES.md (testing standards)
-  - CODING-PRINCIPLES.md (code quality standards)
-  - DOCUMENTATION-CRITERIA.md (documentation standards)
-  - AI-DEVELOPMENT-GUIDE.md (AI-assisted development best practices)
-- `.claude/trinity/templates/` - Reusable templates
-  - `documentation/` - Documentation templates (2 README templates + 23 report templates)
-  - `investigations/` - 5 investigation templates (bug, feature, performance, security, technical)
-  - `work-orders/` - 6 work order templates
-- `.claude/trinity/investigations/` - Active investigations with execution plans
-- `.claude/trinity/sessions/` - Session archives
-- `.claude/trinity/reports/` - Audit and integration reports
-- `.claude/trinity/work-orders/` - Active work orders
-- `.claude/trinity/archive/` - Archived sessions, reports, and investigations
-
-**Agent System:**
-
-- `.claude/agents/` - 18 specialized agents organized by category:
-  - `aj-team/` - 7 execution agents (APO, BAS, BON, CAP, DRA, KIL, URO)
-  - `audit/` - 1 quality auditor (JUNO)
-  - `deployment/` - 4 infrastructure agents (EIN, INO, TAN, ZEN)
-  - `leadership/` - 2 orchestration agents (ALY, AJ MAESTRO)
-  - `planning/` - 4 planning agents (MON, ROR, EUS, TRA)
-- `.claude/commands/` - 21 slash commands organized in 7 categories:
-  - `execution/` - 3 commands (orchestrate, audit, breakdown)
-  - `infrastructure/` - 1 command (init)
-  - `investigation/` - 3 commands (create-investigation, plan-investigation, investigate-templates)
-  - `maintenance/` - 4 commands (readme, docs, docs-update, changelog)
-  - `planning/` - 4 commands (requirements, design, decompose, plan)
-  - `session/` - 3 commands (start, continue, end)
-  - `utility/` - 3 commands (verify, agents, workorder)
-- `.claude/EMPLOYEE-DIRECTORY.md` - Complete 18-agent team guide
-
-**Context Hierarchy:**
-
-- Root `CLAUDE.md` - Global project context
-- `.claude/trinity/CLAUDE.md` - Trinity Method enforcement
-- `src/CLAUDE.md` - Technology-specific rules
-
-**Quality Automation:**
-
-- Linting tools (ESLint, Prettier, Black, Flake8, Clippy, Rustfmt)
-- Pre-commit hooks (Husky + lint-staged for Node.js; Python's pre-commit framework for Python, Flutter, Rust)
-- Automatic dependency injection to package.json/requirements.txt
-- Real codebase metrics: TODO counts, console statements, file complexity, git metrics
-
----
-
-## How Trinity Works
-
-### Installation
-
-#### Option 1: Use npx (Recommended - No installation needed)
-
-```bash
-# Runs latest version without installing
-npx trinity-method-sdk deploy
-```
-
-#### Option 2: Global Installation
-
-```bash
-# Install once globally
-npm install -g trinity-method-sdk
-
-# Then use anywhere
-trinity deploy
-```
-
-### Quick Start (90 Seconds to Production)
-
-```bash
-# Navigate to your project
-cd your-project
-
-# Deploy Trinity Method (using npx)
-npx trinity-method-sdk deploy
-```
-
-**Interactive Wizard:**
-
-1. ✅ **Stack Detection**: Automatically detects framework (Node.js, Python, Rust, Flutter, Go)
-2. ✅ **Linting Setup**: Choose "Recommended" for one-click best practices
-3. ✅ **Deploy**: 90-second deployment with full infrastructure
-4. ✅ **Install Dependencies**: `npm install` (or `pip install -r requirements-dev.txt`)
-5. ✅ **Setup Hooks**: Automatic for Node.js (Husky via `npm install`);
-   for Python/Flutter/Rust: `pip install pre-commit && pre-commit install`
-
-**Result:** Production-ready development environment with 18 agents, 21 slash commands, quality gates, and documentation.
-
-### Available Commands
-
-```bash
-# Deploy Trinity to your project
-npx trinity-method-sdk deploy
-
-# Update Trinity to latest version
-npx trinity-method-sdk update
-```
-
-### Using Trinity Method (Slash Commands)
-
-After deployment, access Trinity functionality through Claude Code slash commands:
-
-**Session Management:**
-
-- `/trinity-start` - Start workflow guide
-- `/trinity-continue` - Resume after interruption
-- `/trinity-end` - End session and archive
-
-**Planning:**
-
-- `/trinity-requirements` - Analyze requirements (MON)
-- `/trinity-design` - Create technical design (ROR)
-- `/trinity-decompose` - Break down tasks (EUS)
-- `/trinity-plan` - Create implementation plan (TRA)
-
-**Execution:**
-
-- `/trinity-orchestrate` - Execute with ALY orchestration
-- `/trinity-audit` - Run codebase audit (JUNO)
-- `/trinity-breakdown` - Guided step-by-step implementation walkthrough
-
-**Maintenance:**
-
-- `/trinity-readme` - Update README coverage (APO)
-- `/trinity-docs` - Generate new documentation (JUNO + 3 parallel APOs)
-- `/trinity-docs-update` - Update existing documentation (JUNO audit → 3 APOs → verification loop)
-- `/trinity-changelog` - Maintain CHANGELOG.md (APO)
-
-**Investigation:**
-
-- `/trinity-create-investigation` - Create structured investigation
-- `/trinity-plan-investigation` - Generate investigation plan
-- `/trinity-investigate-templates` - View investigation templates
-
-**Infrastructure:**
-
-- `/trinity-init` - Initialize Trinity configuration
-
-**Utility:**
-
-- `/trinity-verify` - Verify Trinity deployment
-- `/trinity-agents` - View agent directory
-- `/trinity-workorder` - Create work orders
-
-### Linting & Code Quality (85-90% Time Savings)
-
-#### Before Trinity (Manual Setup): ~50 minutes per project
-
-1. Research tools for your framework
-2. Install dependencies
-3. Create configuration files
-4. Configure pre-commit hooks
-5. Test and debug configuration
-
-#### With Trinity (Automated): ~6 minutes per project
-
-1. Select "Recommended" during deployment (30 seconds)
-2. Run `npm install` (3-5 minutes, automatically sets up Husky hooks for Node.js)
-3. For Python/Flutter/Rust only: `pip install pre-commit && pre-commit install` (30 seconds)
-
-**Supported Frameworks:**
-
-- **Node.js/React**: ESLint + Prettier + Husky + lint-staged
-- **Python**: Black + Flake8 + isort + Pre-commit
-- **Flutter**: Dart Analyzer + Pre-commit
-- **Rust**: Clippy + Rustfmt + Pre-commit
-
----
-
-## Designed for Claude Code
-
-Trinity Method SDK is built exclusively for
-[Claude Code](https://claude.com/claude-code), Anthropic's AI pair programming environment.
-
-### Why Claude Code
-
-- **Deep Integration**: Trinity's 18-agent team leverages Claude Code's agent architecture
-- **Slash Commands**: Built-in `/trinity-*` commands for instant workflow access
-- **Context System**: Layered CLAUDE.md hierarchy for persistent project knowledge
-- **Quality Focus**: Exceptional single-agent experience optimized for Claude
-
-### Other AI Assistants
-
-The Trinity Method **philosophy** is agent-agnostic, but this SDK is optimized for Claude Code's
-capabilities. Want to use Trinity with Cursor, Copilot, or others? We welcome contributions!
-See [CONTRIBUTING.md](./CONTRIBUTING.md).
-
----
-
-## Examples & Documentation
-
-### Real-World Deployments
-
-```bash
-# Node.js/Express API
-cd my-api && npx trinity-method-sdk deploy
-# Result: API with ESLint, Prettier, Husky, 18 agents, quality gates
-
-# Python/Django Project
-cd my-django && npx trinity-method-sdk deploy
-# Result: Django with Black, Flake8, isort, pre-commit, full Trinity infrastructure
-
-# Flutter Mobile App
-cd my-flutter-app && npx trinity-method-sdk deploy
-# Result: Flutter with Dart Analyzer, pre-commit, investigation templates
-
-# Rust CLI Tool
-cd my-rust-cli && npx trinity-method-sdk deploy
-# Result: Rust with Clippy, Rustfmt, pre-commit, crisis management
-```
-
-### Documentation
-
-After deploying Trinity to your project, comprehensive documentation is available in your project:
-
-**Trinity Knowledge Base:**
-
-- `.claude/trinity/knowledge-base/ARCHITECTURE.md` - System architecture with codebase metrics
-- `.claude/trinity/knowledge-base/ISSUES.md` - Known issues and bug tracking
-- `.claude/trinity/knowledge-base/To-do.md` - Task management and priorities
-- `.claude/trinity/knowledge-base/Technical-Debt.md` - Technical debt tracking
-- `.claude/trinity/knowledge-base/Trinity.md` - Project-specific Trinity guide
-- `.claude/trinity/knowledge-base/TESTING-PRINCIPLES.md` - Testing standards
-- `.claude/trinity/knowledge-base/CODING-PRINCIPLES.md` - Code quality standards
-
-**Agent System:**
-
-- `.claude/EMPLOYEE-DIRECTORY.md` - Complete agent reference and selection guide
-- `.claude/agents/` - 18 specialized agent markdown files
-
-**SDK Documentation:**
-
-- [API Documentation](docs/) - TypeDoc-generated API reference
-- [CONTRIBUTING.md](CONTRIBUTING.md) - Development setup, workflow, and standards
-- [CHANGELOG.md](CHANGELOG.md) - Version history and release notes
-
-### After Deployment
-
-Your project contains:
-
-- **88 production-ready components** deployed in 90 seconds
-- **18 specialized agents** in `.claude/agents/` (7 execution + 1 audit + 4 deployment + 2 leadership + 4 planning)
-- **21 slash commands** in `.claude/commands/`
-  (3 execution + 1 infrastructure + 3 investigation + 4 maintenance + 4 planning + 3 session + 3 utility)
-- **Complete knowledge base** in `.claude/trinity/knowledge-base/` (ARCHITECTURE.md, ISSUES.md, To-do.md, Technical-Debt.md)
-- **Investigation templates** in `.claude/trinity/templates/investigations/` (bug, feature, performance, security, technical)
-- **Work order templates** in `.claude/trinity/templates/work-orders/`
-- **Session archives** in `.claude/trinity/sessions/`
-- **Audit reports** in `.claude/trinity/reports/`
-- **Linting tools** configured for your framework
-
-**Complete Deployed Structure:**
-
-```text
-your-project/
-├── .claude/
-│   ├── agents/
-│   │   ├── aj-team/              # 7 execution agents (APO, BAS, BON, CAP, DRA, KIL, URO)
-│   │   ├── audit/                # 1 quality auditor (JUNO)
-│   │   ├── deployment/           # 4 infrastructure agents (EIN, INO, TAN, ZEN)
-│   │   ├── leadership/           # 2 orchestration agents (ALY, AJ MAESTRO)
-│   │   └── planning/             # 4 planning agents (MON, ROR, EUS, TRA)
-│   ├── commands/
-│   │   ├── execution/            # trinity-orchestrate, trinity-audit, trinity-breakdown
-│   │   ├── infrastructure/       # trinity-init
-│   │   ├── investigation/        # trinity-create-investigation, trinity-plan-investigation, trinity-investigate-templates
-│   │   ├── maintenance/          # trinity-readme, trinity-docs, trinity-docs-update, trinity-changelog
-│   │   ├── planning/             # trinity-requirements, trinity-design, trinity-decompose, trinity-plan
-│   │   ├── session/              # trinity-start, trinity-continue, trinity-end
-│   │   └── utility/              # trinity-verify, trinity-agents, trinity-workorder
-│   ├── trinity/
-│   │   ├── knowledge-base/       # ARCHITECTURE.md, ISSUES.md, To-do.md, Technical-Debt.md, Trinity.md
-│   │   ├── templates/
-│   │   │   ├── documentation/    # 2 README templates + 23 report templates
-│   │   │   ├── investigations/   # 5 investigation templates (bug, feature, performance, security, technical)
-│   │   │   └── work-orders/      # 6 work order templates
-│   │   ├── investigations/       # Active investigations
-│   │   │   └── plans/            # Investigation execution plans
-│   │   ├── sessions/             # Session archives
-│   │   ├── reports/              # Audit and integration reports
-│   │   ├── work-orders/          # Active work orders
-│   │   └── archive/              # Archived sessions, reports, investigations
-│   └── EMPLOYEE-DIRECTORY.md     # 18-agent team guide
-├── CLAUDE.md                     # Root context file
-└── src/CLAUDE.md                 # Framework-specific context
-```
-
-- **Pre-commit hooks** automatically enforcing quality standards
-
----
-
-## Contributing
-
-Trinity Method SDK is open source and welcomes contributions!
-
-**Ways to Contribute:**
-
-- 🐛 Report bugs and issues
-- 💡 Suggest new features or agent improvements
-- 📝 Improve documentation
-- 🔧 Submit pull requests
-- ⭐ Star the repository if you find it useful
-
-**Development Setup:**
-
-```bash
-# Clone repository
-git clone https://github.com/lukadfagundes/trinity-method-sdk.git
-cd trinity-method-sdk
-
-# Install dependencies
-npm install
-
-# Build SDK
-npm run build
-
-# Test locally
-npm link
-trinity deploy
-```
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
-
----
-
-## Development & Publishing
-
-### CI/CD Pipeline
-
-Trinity uses GitHub Actions for comprehensive continuous integration and deployment with BAS 6-phase quality gates.
-
-#### Continuous Integration (CI)
-
-**Automated Quality Checks on Every Push:**
-
-- ✅ Multi-platform testing (Ubuntu, Windows, macOS)
-- ✅ Multi-version testing (Node.js 18.x, 20.x, 22.x)
-- ✅ Trinity component validation (18 agents, 21 slash commands, knowledge base, CI/CD templates)
-- ✅ Test suite execution (unit, integration, e2e, performance)
-- ✅ Code coverage validation (80%+ threshold enforced)
-- ✅ Linting and type checking
-- ✅ Security scanning (npm audit, dependency checks)
-- ✅ Build verification with artifact validation
-- ✅ Documentation validation
-
-**BAS 6-Phase Quality Gates:**
-
-1. **Phase 1**: Code Quality (Linting, type checking, formatting)
-2. **Phase 2**: Structure Validation (Trinity template validation)
-3. **Phase 3**: Build Validation (TypeScript compilation, artifact verification)
-4. **Phase 4**: Testing (All test suites across platforms)
-5. **Phase 5**: Coverage Check (≥80% threshold)
-6. **Phase 6**: Documentation (API docs, README validation)
-
-**CI Workflow Location:** [.github/workflows/ci.yml](.github/workflows/ci.yml)
-
-#### Publishing to npm
-
-**Manual Publishing Workflow:**
-
-```bash
-# 1. Update version and changelog
-npm version patch  # or minor, major
-
-# 2. Build and publish
-npm run build
-npm publish --access public
-
-# 3. Create git tag and push
-git tag -a vX.Y.Z -m "Release vX.Y.Z"
-git push origin main --follow-tags
-```
-
-**Automated Checks Before Publishing:**
-
-The `prepublishOnly` script runs automatically before every publish:
-
-1. TypeScript compilation (`npm run build`)
-2. Template copying to dist/
-3. Full test suite execution (`npm run test`)
-4. Only publishes if all checks pass
-
----
-
-## License
-
-MIT License - see [LICENSE](LICENSE) for details
-
----
-
-## Links
-
-### Project Resources
-
-- **npm Package**: [trinity-method-sdk](https://www.npmjs.com/package/trinity-method-sdk)
-- **GitHub**: [lukadfagundes/trinity-method-sdk](https://github.com/lukadfagundes/trinity-method-sdk)
-- **Issues**: [GitHub Issues](https://github.com/lukadfagundes/trinity-method-sdk/issues)
-- **Discussions**: [GitHub Discussions](https://github.com/lukadfagundes/trinity-method-sdk/discussions)
-
-### Documentation
-
-- **API Documentation**: [docs/](docs/) - Generated TypeDoc API reference
-- **Contributing Guide**: [CONTRIBUTING.md](CONTRIBUTING.md) - Development setup, workflow, and standards
-- **Changelog**: [CHANGELOG.md](CHANGELOG.md) - Version history and release notes
-
----
+# Trinity Method SDK
+
+[![npm version](https://img.shields.io/npm/v/trinity-method-sdk?color=success)](https://www.npmjs.com/package/trinity-method-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D16.9.0-brightgreen)](https://nodejs.org/)
+[![AI Agents](https://img.shields.io/badge/AI%20Agent-Claude%20Code-blue)](https://github.com/lukadfagundes/trinity-method-sdk)
+
+> Investigation-first development methodology for Claude Code
+
+---
+
+## Why Trinity Method Exists
+
+### The Problem with Traditional AI-Assisted Development
+
+AI coding assistants are powerful, but without structure they become expensive guessing machines:
+
+**❌ Jump-to-Code Anti-Pattern:**
+
+- AI generates code without understanding the problem
+- No investigation phase → immediate implementation
+- Context lost between sessions → repeated mistakes
+- No institutional knowledge → every session starts from zero
+- Inconsistent quality → success depends on prompt luck
+- Manual quality setup → 50 minutes configuring linters per project
+
+**The Cost:**
+
+- Developers waste time debugging AI-generated code that solves the wrong problem
+- Teams lose hard-won lessons when developers leave
+- Technical debt accumulates invisibly
+- Code quality varies wildly across sessions
+
+### Our Philosophy: Investigation-First Development
+
+Trinity Method rejects "prompt and pray" development. Instead, we enforce **systematic investigation before implementation**:
+
+#### 1. Investigation-First Principle
+
+```text
+WRONG: "Build authentication" → AI generates code → Debug for hours
+RIGHT: "Investigate authentication requirements" → Understand problem → Design solution → Implement correctly
+```
+
+#### 2. Evidence-Based Decisions
+
+Every decision backed by documentation, codebase metrics, and historical patterns. No guessing.
+
+**3. Knowledge Preservation**
+Lessons learned persist across sessions through institutional memory. Agents get smarter over time.
+
+**4. Systematic Quality Assurance**
+Quality isn't aspirational—it's systematically enforced through automated gates (BAS 6-phase validation).
+
+### The Trinity Transformation
+
+**✅ With Trinity Method:**
+
+- **Investigation before coding** → Understand the problem first
+- **Persistent knowledge base** → Learn from every session
+- **Automated quality enforcement** → BAS gates ensure standards
+- **18-agent team coordination** → Right specialist for each task
+- **Institutional memory** → Patterns, strategies, and lessons preserved
+- **90-second deployment** → Complete development environment instantly
+
+---
+
+## What is Trinity Method SDK
+
+Trinity Method SDK is a **production-ready development methodology** that transforms AI-assisted coding
+from random generation into systematic engineering.
+
+### Core Philosophy
+
+**Trinity Method enforces three pillars:**
+
+1. **Investigation-First Development**
+   - Systematic investigation using MON (Requirements), ROR (Design), TRA (Planning)
+   - Evidence-based decisions backed by documentation and metrics
+   - Scale-based workflows: SMALL (0 stop points) → MEDIUM (2 stop points) → LARGE (4 stop points)
+
+2. **Knowledge Preservation**
+   - Learning system captures patterns from every investigation
+   - Cross-session persistence through filesystem storage
+   - Agent knowledge sharing via pub/sub bus (≥0.8 confidence threshold)
+
+3. **Systematic Quality Assurance**
+   - BAS 6-phase quality gate: Lint → Structure → Build → Test → Coverage (≥80%) → Review
+   - Crisis management system for 5 crisis types (build, test, error, performance, security)
+   - Automated codebase metrics collection and technical debt tracking
+
+### The 18-Agent Team
+
+Trinity SDK includes **18 specialized agents** organized across 5 functional teams:
+
+**Planning Layer:**
+
+- **MON** - Requirements Analyst (functional & non-functional requirements)
+- **ROR** - Design Architect (technical design, ADRs)
+- **TRA** - Work Planner (implementation sequencing, BAS integration)
+- **EUS** - Task Decomposer (atomic task breakdown)
+
+**Execution Layer:**
+
+- **KIL** - Task Executor (TDD implementation: RED → GREEN → REFACTOR)
+- **BAS** - Quality Gate (6-phase validation enforcer)
+- **DRA** - Code Reviewer (design doc compliance, quality escalation)
+
+**Support Layer:**
+
+- **APO** - Documentation Specialist (API docs, inline comments)
+- **BON** - Dependency Manager (package security, version management)
+- **CAP** - Configuration Specialist (env vars, config files)
+- **URO** - Refactoring Specialist (technical debt reduction)
+
+**Leadership:**
+
+- **ALY** - Chief Technology Officer (investigation orchestration, strategic coordination)
+- **AJ MAESTRO** - Orchestrator (multi-agent workflow orchestration, task delegation)
+
+**Deployment:**
+
+- **TAN** - Structure Specialist (directory structure validation)
+- **ZEN** - Knowledge Base Specialist (comprehensive documentation)
+- **INO** - Context Specialist (CLAUDE.md hierarchy management)
+- **EIN** - CI/CD Specialist (continuous integration/deployment automation)
+
+**Audit:**
+
+- **JUNO** - Quality Auditor (comprehensive codebase audits, deployment verification)
+
+### What Gets Deployed
+
+Trinity deploys **88 production-ready components** in 90 seconds:
+
+**Methodology Infrastructure:**
+
+- `.claude/trinity/knowledge-base/` - 9 living documentation files
+  - ARCHITECTURE.md (codebase metrics, architecture documentation)
+  - ISSUES.md (known issues and bug tracking)
+  - To-do.md (task management and priorities)
+  - Technical-Debt.md (technical debt tracking)
+  - Trinity.md (project-specific Trinity guide)
+  - TESTING-PRINCIPLES.md (testing standards)
+  - CODING-PRINCIPLES.md (code quality standards)
+  - DOCUMENTATION-CRITERIA.md (documentation standards)
+  - AI-DEVELOPMENT-GUIDE.md (AI-assisted development best practices)
+- `.claude/trinity/templates/` - Reusable templates
+  - `documentation/` - Documentation templates (2 README templates + 23 report templates)
+  - `investigations/` - 5 investigation templates (bug, feature, performance, security, technical)
+  - `work-orders/` - 6 work order templates
+- `.claude/trinity/investigations/` - Active investigations with execution plans
+- `.claude/trinity/sessions/` - Session archives
+- `.claude/trinity/reports/` - Audit and integration reports
+- `.claude/trinity/work-orders/` - Active work orders
+- `.claude/trinity/archive/` - Archived sessions, reports, and investigations
+
+**Agent System:**
+
+- `.claude/agents/` - 18 specialized agents organized by category:
+  - `aj-team/` - 7 execution agents (APO, BAS, BON, CAP, DRA, KIL, URO)
+  - `audit/` - 1 quality auditor (JUNO)
+  - `deployment/` - 4 infrastructure agents (EIN, INO, TAN, ZEN)
+  - `leadership/` - 2 orchestration agents (ALY, AJ MAESTRO)
+  - `planning/` - 4 planning agents (MON, ROR, EUS, TRA)
+- `.claude/commands/` - 21 slash commands organized in 7 categories:
+  - `execution/` - 3 commands (orchestrate, audit, breakdown)
+  - `infrastructure/` - 1 command (init)
+  - `investigation/` - 3 commands (create-investigation, plan-investigation, investigate-templates)
+  - `maintenance/` - 4 commands (readme, docs, docs-update, changelog)
+  - `planning/` - 4 commands (requirements, design, decompose, plan)
+  - `session/` - 3 commands (start, continue, end)
+  - `utility/` - 3 commands (verify, agents, workorder)
+- `.claude/EMPLOYEE-DIRECTORY.md` - Complete 18-agent team guide
+
+**Context Hierarchy:**
+
+- Root `CLAUDE.md` - Global project context
+- `.claude/trinity/CLAUDE.md` - Trinity Method enforcement
+- `src/CLAUDE.md` - Technology-specific rules
+
+**Quality Automation:**
+
+- Linting tools (ESLint, Prettier, Black, Flake8, Clippy, Rustfmt)
+- Pre-commit hooks (Husky + lint-staged for Node.js; Python's pre-commit framework for Python, Flutter, Rust)
+- Automatic dependency injection to package.json/requirements.txt
+- Real codebase metrics: TODO counts, console statements, file complexity, git metrics
+
+---
+
+## How Trinity Works
+
+### Installation
+
+#### Option 1: Use npx (Recommended - No installation needed)
+
+```bash
+# Runs latest version without installing
+npx trinity-method-sdk deploy
+```
+
+#### Option 2: Global Installation
+
+```bash
+# Install once globally
+npm install -g trinity-method-sdk
+
+# Then use anywhere
+trinity deploy
+```
+
+### Quick Start (90 Seconds to Production)
+
+```bash
+# Navigate to your project
+cd your-project
+
+# Deploy Trinity Method (using npx)
+npx trinity-method-sdk deploy
+```
+
+**Interactive Wizard:**
+
+1. ✅ **Stack Detection**: Automatically detects framework (Node.js, Python, Rust, Flutter, Go)
+2. ✅ **Linting Setup**: Choose "Recommended" for one-click best practices
+3. ✅ **Deploy**: 90-second deployment with full infrastructure
+4. ✅ **Install Dependencies**: `npm install` (or `pip install -r requirements-dev.txt`)
+5. ✅ **Setup Hooks**: Automatic for Node.js (Husky via `npm install`);
+   for Python/Flutter/Rust: `pip install pre-commit && pre-commit install`
+
+**Result:** Production-ready development environment with 18 agents, 21 slash commands, quality gates, and documentation.
+
+### Available Commands
+
+```bash
+# Deploy Trinity to your project
+npx trinity-method-sdk deploy
+
+# Update Trinity to latest version
+npx trinity-method-sdk update
+```
+
+### Using Trinity Method (Slash Commands)
+
+After deployment, access Trinity functionality through Claude Code slash commands:
+
+**Session Management:**
+
+- `/trinity-start` - Start workflow guide
+- `/trinity-continue` - Resume after interruption
+- `/trinity-end` - End session and archive
+
+**Planning:**
+
+- `/trinity-requirements` - Analyze requirements (MON)
+- `/trinity-design` - Create technical design (ROR)
+- `/trinity-decompose` - Break down tasks (EUS)
+- `/trinity-plan` - Create implementation plan (TRA)
+
+**Execution:**
+
+- `/trinity-orchestrate` - Execute with ALY orchestration
+- `/trinity-audit` - Run codebase audit (JUNO)
+- `/trinity-breakdown` - Guided step-by-step implementation walkthrough
+
+**Maintenance:**
+
+- `/trinity-readme` - Update README coverage (APO)
+- `/trinity-docs` - Generate new documentation (JUNO + 3 parallel APOs)
+- `/trinity-docs-update` - Update existing documentation (JUNO audit → 3 APOs → verification loop)
+- `/trinity-changelog` - Maintain CHANGELOG.md (APO)
+
+**Investigation:**
+
+- `/trinity-create-investigation` - Create structured investigation
+- `/trinity-plan-investigation` - Generate investigation plan
+- `/trinity-investigate-templates` - View investigation templates
+
+**Infrastructure:**
+
+- `/trinity-init` - Initialize Trinity configuration
+
+**Utility:**
+
+- `/trinity-verify` - Verify Trinity deployment
+- `/trinity-agents` - View agent directory
+- `/trinity-workorder` - Create work orders
+
+### Linting & Code Quality (85-90% Time Savings)
+
+#### Before Trinity (Manual Setup): ~50 minutes per project
+
+1. Research tools for your framework
+2. Install dependencies
+3. Create configuration files
+4. Configure pre-commit hooks
+5. Test and debug configuration
+
+#### With Trinity (Automated): ~6 minutes per project
+
+1. Select "Recommended" during deployment (30 seconds)
+2. Run `npm install` (3-5 minutes, automatically sets up Husky hooks for Node.js)
+3. For Python/Flutter/Rust only: `pip install pre-commit && pre-commit install` (30 seconds)
+
+**Supported Frameworks:**
+
+- **Node.js/React**: ESLint + Prettier + Husky + lint-staged
+- **Python**: Black + Flake8 + isort + Pre-commit
+- **Flutter**: Dart Analyzer + Pre-commit
+- **Rust**: Clippy + Rustfmt + Pre-commit
+
+---
+
+## Designed for Claude Code
+
+Trinity Method SDK is built exclusively for
+[Claude Code](https://claude.com/claude-code), Anthropic's AI pair programming environment.
+
+### Why Claude Code
+
+- **Deep Integration**: Trinity's 18-agent team leverages Claude Code's agent architecture
+- **Slash Commands**: Built-in `/trinity-*` commands for instant workflow access
+- **Context System**: Layered CLAUDE.md hierarchy for persistent project knowledge
+- **Quality Focus**: Exceptional single-agent experience optimized for Claude
+
+### Other AI Assistants
+
+The Trinity Method **philosophy** is agent-agnostic, but this SDK is optimized for Claude Code's
+capabilities. Want to use Trinity with Cursor, Copilot, or others? We welcome contributions!
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+---
+
+## Examples & Documentation
+
+### Real-World Deployments
+
+```bash
+# Node.js/Express API
+cd my-api && npx trinity-method-sdk deploy
+# Result: API with ESLint, Prettier, Husky, 18 agents, quality gates
+
+# Python/Django Project
+cd my-django && npx trinity-method-sdk deploy
+# Result: Django with Black, Flake8, isort, pre-commit, full Trinity infrastructure
+
+# Flutter Mobile App
+cd my-flutter-app && npx trinity-method-sdk deploy
+# Result: Flutter with Dart Analyzer, pre-commit, investigation templates
+
+# Rust CLI Tool
+cd my-rust-cli && npx trinity-method-sdk deploy
+# Result: Rust with Clippy, Rustfmt, pre-commit, crisis management
+```
+
+### Documentation
+
+After deploying Trinity to your project, comprehensive documentation is available in your project:
+
+**Trinity Knowledge Base:**
+
+- `.claude/trinity/knowledge-base/ARCHITECTURE.md` - System architecture with codebase metrics
+- `.claude/trinity/knowledge-base/ISSUES.md` - Known issues and bug tracking
+- `.claude/trinity/knowledge-base/To-do.md` - Task management and priorities
+- `.claude/trinity/knowledge-base/Technical-Debt.md` - Technical debt tracking
+- `.claude/trinity/knowledge-base/Trinity.md` - Project-specific Trinity guide
+- `.claude/trinity/knowledge-base/TESTING-PRINCIPLES.md` - Testing standards
+- `.claude/trinity/knowledge-base/CODING-PRINCIPLES.md` - Code quality standards
+
+**Agent System:**
+
+- `.claude/EMPLOYEE-DIRECTORY.md` - Complete agent reference and selection guide
+- `.claude/agents/` - 18 specialized agent markdown files
+
+**SDK Documentation:**
+
+- [API Documentation](docs/) - TypeDoc-generated API reference
+- [CONTRIBUTING.md](CONTRIBUTING.md) - Development setup, workflow, and standards
+- [CHANGELOG.md](CHANGELOG.md) - Version history and release notes
+
+### After Deployment
+
+Your project contains:
+
+- **88 production-ready components** deployed in 90 seconds
+- **18 specialized agents** in `.claude/agents/` (7 execution + 1 audit + 4 deployment + 2 leadership + 4 planning)
+- **21 slash commands** in `.claude/commands/`
+  (3 execution + 1 infrastructure + 3 investigation + 4 maintenance + 4 planning + 3 session + 3 utility)
+- **Complete knowledge base** in `.claude/trinity/knowledge-base/` (ARCHITECTURE.md, ISSUES.md, To-do.md, Technical-Debt.md)
+- **Investigation templates** in `.claude/trinity/templates/investigations/` (bug, feature, performance, security, technical)
+- **Work order templates** in `.claude/trinity/templates/work-orders/`
+- **Session archives** in `.claude/trinity/sessions/`
+- **Audit reports** in `.claude/trinity/reports/`
+- **Linting tools** configured for your framework
+
+**Complete Deployed Structure:**
+
+```text
+your-project/
+├── .claude/
+│   ├── agents/
+│   │   ├── aj-team/              # 7 execution agents (APO, BAS, BON, CAP, DRA, KIL, URO)
+│   │   ├── audit/                # 1 quality auditor (JUNO)
+│   │   ├── deployment/           # 4 infrastructure agents (EIN, INO, TAN, ZEN)
+│   │   ├── leadership/           # 2 orchestration agents (ALY, AJ MAESTRO)
+│   │   └── planning/             # 4 planning agents (MON, ROR, EUS, TRA)
+│   ├── commands/
+│   │   ├── execution/            # trinity-orchestrate, trinity-audit, trinity-breakdown
+│   │   ├── infrastructure/       # trinity-init
+│   │   ├── investigation/        # trinity-create-investigation, trinity-plan-investigation, trinity-investigate-templates
+│   │   ├── maintenance/          # trinity-readme, trinity-docs, trinity-docs-update, trinity-changelog
+│   │   ├── planning/             # trinity-requirements, trinity-design, trinity-decompose, trinity-plan
+│   │   ├── session/              # trinity-start, trinity-continue, trinity-end
+│   │   └── utility/              # trinity-verify, trinity-agents, trinity-workorder
+│   ├── trinity/
+│   │   ├── knowledge-base/       # ARCHITECTURE.md, ISSUES.md, To-do.md, Technical-Debt.md, Trinity.md
+│   │   ├── templates/
+│   │   │   ├── documentation/    # 2 README templates + 23 report templates
+│   │   │   ├── investigations/   # 5 investigation templates (bug, feature, performance, security, technical)
+│   │   │   └── work-orders/      # 6 work order templates
+│   │   ├── investigations/       # Active investigations
+│   │   │   └── plans/            # Investigation execution plans
+│   │   ├── sessions/             # Session archives
+│   │   ├── reports/              # Audit and integration reports
+│   │   ├── work-orders/          # Active work orders
+│   │   └── archive/              # Archived sessions, reports, investigations
+│   └── EMPLOYEE-DIRECTORY.md     # 18-agent team guide
+├── CLAUDE.md                     # Root context file
+└── src/CLAUDE.md                 # Framework-specific context
+```
+
+- **Pre-commit hooks** automatically enforcing quality standards
+
+---
+
+## Contributing
+
+Trinity Method SDK is open source and welcomes contributions!
+
+**Ways to Contribute:**
+
+- 🐛 Report bugs and issues
+- 💡 Suggest new features or agent improvements
+- 📝 Improve documentation
+- 🔧 Submit pull requests
+- ⭐ Star the repository if you find it useful
+
+**Development Setup:**
+
+```bash
+# Clone repository
+git clone https://github.com/lukadfagundes/trinity-method-sdk.git
+cd trinity-method-sdk
+
+# Install dependencies
+npm install
+
+# Build SDK
+npm run build
+
+# Test locally
+npm link
+trinity deploy
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
+
+---
+
+## Development & Publishing
+
+### CI/CD Pipeline
+
+Trinity uses GitHub Actions for comprehensive continuous integration and deployment with BAS 6-phase quality gates.
+
+#### Continuous Integration (CI)
+
+**Automated Quality Checks on Every Push:**
+
+- ✅ Multi-platform testing (Ubuntu, Windows, macOS)
+- ✅ Multi-version testing (Node.js 18.x, 20.x, 22.x)
+- ✅ Trinity component validation (18 agents, 21 slash commands, knowledge base, CI/CD templates)
+- ✅ Test suite execution (unit, integration, e2e, performance)
+- ✅ Code coverage validation (80%+ threshold enforced)
+- ✅ Linting and type checking
+- ✅ Security scanning (npm audit, dependency checks)
+- ✅ Build verification with artifact validation
+- ✅ Documentation validation
+
+**BAS 6-Phase Quality Gates:**
+
+1. **Phase 1**: Code Quality (Linting, type checking, formatting)
+2. **Phase 2**: Structure Validation (Trinity template validation)
+3. **Phase 3**: Build Validation (TypeScript compilation, artifact verification)
+4. **Phase 4**: Testing (All test suites across platforms)
+5. **Phase 5**: Coverage Check (≥80% threshold)
+6. **Phase 6**: Documentation (API docs, README validation)
+
+**CI Workflow Location:** [.github/workflows/ci.yml](.github/workflows/ci.yml)
+
+#### Publishing to npm
+
+**Manual Publishing Workflow:**
+
+```bash
+# 1. Update version and changelog
+npm version patch  # or minor, major
+
+# 2. Build and publish
+npm run build
+npm publish --access public
+
+# 3. Create git tag and push
+git tag -a vX.Y.Z -m "Release vX.Y.Z"
+git push origin main --follow-tags
+```
+
+**Automated Checks Before Publishing:**
+
+The `prepublishOnly` script runs automatically before every publish:
+
+1. TypeScript compilation (`npm run build`)
+2. Template copying to dist/
+3. Full test suite execution (`npm run test`)
+4. Only publishes if all checks pass
+
+---
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details
+
+---
+
+## Links
+
+### Project Resources
+
+- **npm Package**: [trinity-method-sdk](https://www.npmjs.com/package/trinity-method-sdk)
+- **GitHub**: [lukadfagundes/trinity-method-sdk](https://github.com/lukadfagundes/trinity-method-sdk)
+- **Issues**: [GitHub Issues](https://github.com/lukadfagundes/trinity-method-sdk/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/lukadfagundes/trinity-method-sdk/discussions)
+
+### Documentation
+
+- **API Documentation**: [docs/](docs/) - Generated TypeDoc API reference
+- **Contributing Guide**: [CONTRIBUTING.md](CONTRIBUTING.md) - Development setup, workflow, and standards
+- **Changelog**: [CHANGELOG.md](CHANGELOG.md) - Version history and release notes
+
+---

package/dist/cli/commands/deploy/gitignore.js

@@ -18,14 +18,8 @@ export async function updateGitignore(spinner) {
         if (await fs.pathExists(gitignorePath)) {
             gitignoreContent = await fs.readFile(gitignorePath, 'utf8');
         }
-        // Trinity files to ignore (archive and templates are ephemeral/generated)
-        const trinityIgnores = [
-            '',
-            '# Trinity Method SDK',
-            '.claude/trinity/archive/',
-            '.claude/trinity/templates/',
-            '*CLAUDE.md',
-        ];
+        // Trinity files to ignore (entire .claude/ directory and all CLAUDE.md files)
+        const trinityIgnores = ['', '# Trinity Method SDK', '.claude/', '*CLAUDE.md'];
         // Check if Trinity section already exists
         if (!gitignoreContent.includes('# Trinity Method SDK')) {
             // Append Trinity ignores

package/dist/cli/commands/update/migration.js

@@ -6,14 +6,15 @@
 import fs from 'fs-extra';
 import path from 'path';
 import { validatePath } from '../../utils/validate-path.js';
-/** Old gitignore patterns from pre-2.2.0 deployments */
-const OLD_GITIGNORE_PATTERNS = ['trinity/', '*CLAUDE.md', 'TRINITY.md'];
-/** Current gitignore patterns */
-const CURRENT_GITIGNORE_PATTERNS = [
+/** Old gitignore patterns from previous deployments */
+const OLD_GITIGNORE_PATTERNS = [
+    'trinity/',
+    'TRINITY.md',
     '.claude/trinity/archive/',
     '.claude/trinity/templates/',
-    '*CLAUDE.md',
 ];
+/** Current gitignore patterns */
+const CURRENT_GITIGNORE_PATTERNS = ['.claude/', '*CLAUDE.md'];
 /**
  * Detect if the project has a legacy (pre-2.2.0) Trinity deployment
  * Legacy deployments use `trinity/` at root instead of `.claude/trinity/`
@@ -97,6 +98,7 @@ export async function updateGitignoreForMigration(spinner) {
                     trimmed === 'trinity/' ||
                     trimmed === '*CLAUDE.md' ||
                     trimmed === 'TRINITY.md' ||
+                    trimmed === '.claude/' ||
                     trimmed === '.claude/trinity/archive/' ||
                     trimmed === '.claude/trinity/templates/') {
                     continue;

package/dist/templates/.claude/commands/session/trinity-end.md.template

@@ -17,17 +17,29 @@ End current Trinity Method session and prepare for commit.
 
    **STRICT ARCHIVING PROTOCOL:**
 
-   a. **Archive Completed Work Orders:**
+   a. **Archive Completed Work Orders from sessions/:**
       - Read all files from `.claude/trinity/sessions/` matching `WO-*.md`
       - Move each to `.claude/trinity/archive/work-orders/YYYY-MM-DD/`
       - These were moved to sessions/ after completion per work order template
 
-   b. **Archive Completed Investigations:**
+   b. **Archive Completed Work Orders from work-orders/:**
+      - Check `.claude/trinity/work-orders/` for any completed work orders
+      - Completed work orders have status marked as "COMPLETED" or "CLOSED"
+      - Move completed ones to `.claude/trinity/archive/work-orders/YYYY-MM-DD/`
+      - Leave active/in-progress work orders in place
+
+   c. **Archive Completed Investigations from sessions/:**
       - Read all files from `.claude/trinity/sessions/` matching `INV-*.md`
       - Move each to `.claude/trinity/archive/investigations/YYYY-MM-DD/`
       - These were moved to sessions/ after completion per investigation template
 
-   c. **Archive ALL Reports:**
+   d. **Archive Completed Investigations from investigations/:**
+      - Check `.claude/trinity/investigations/` for any completed investigations
+      - Move completed ones to `.claude/trinity/archive/investigations/YYYY-MM-DD/`
+      - Also check `.claude/trinity/investigations/plans/` and archive any completed investigation plans
+      - Leave active/in-progress investigations in place
+
+   e. **Archive ALL Reports:**
       - Move ALL files from `.claude/trinity/reports/` to `.claude/trinity/archive/reports/YYYY-MM-DD/`
       - This includes:
         - Implementation completion reports
@@ -36,15 +48,26 @@ End current Trinity Method session and prepare for commit.
         - Any other session reports
       - **NO EXCEPTIONS:** Every file in reports/ must be archived
 
-   d. **Archive Session Files:**
+   f. **Archive Plan Mode Files:**
+      - Move ALL files from `.claude/trinity/plans/` to `.claude/trinity/archive/sessions/YYYY-MM-DD/`
+      - These are created by Claude Code during plan mode sessions
+      - They are session artifacts and should be archived with session files
+
+   g. **Archive Session Files:**
       - Move ALL remaining files from `.claude/trinity/sessions/` to `.claude/trinity/archive/sessions/YYYY-MM-DD/`
       - Create session summary document in `.claude/trinity/archive/sessions/YYYY-MM-DD/SESSION-SUMMARY-{date}.md`
 
-   e. **Verify Clean Slate:**
+   h. **Organize Loose Archive Files:**
+      - Check each `.claude/trinity/archive/` subdirectory (work-orders/, investigations/, reports/, sessions/)
+      - If any files exist directly in a subdirectory (not inside a YYYY-MM-DD/ date folder), move them into the appropriate `YYYY-MM-DD/` folder based on their modification date
+      - This ensures all archived files are properly organized in date folders
+
+   i. **Verify Clean Slate:**
       - **CRITICAL:** After archiving, `.claude/trinity/sessions/` MUST be empty
       - **CRITICAL:** After archiving, `.claude/trinity/reports/` MUST be empty
+      - **CRITICAL:** After archiving, `.claude/trinity/plans/` MUST be empty
       - If any files remain, archive them or report error
-      - Next session MUST start with completely empty sessions/ and reports/ folders
+      - Next session MUST start with completely empty sessions/, reports/, and plans/ folders
 
    **Archive Structure:**
    ```
@@ -56,6 +79,7 @@ End current Trinity Method session and prepare for commit.
    ├── investigations/YYYY-MM-DD/
    │   ├── INV-001-*.md
    │   ├── INV-002-*.md
+   │   ├── INV-001-plan-*.md
    │   └── ...
    ├── reports/YYYY-MM-DD/
    │   ├── WO-001-IMPLEMENTATION-COMPLETE-*.md
@@ -64,6 +88,7 @@ End current Trinity Method session and prepare for commit.
    │   └── ...
    └── sessions/YYYY-MM-DD/
        ├── SESSION-SUMMARY-{date}.md
+       ├── [plan mode files]
        └── [any other session files]
    ```
 
@@ -71,8 +96,10 @@ End current Trinity Method session and prepare for commit.
    - Keep ONLY active/in-progress work orders in `.claude/trinity/work-orders/`
    - Keep ONLY active/in-progress investigations in `.claude/trinity/investigations/`
    - Do NOT archive incomplete work
-   - Completed work is identified by presence in `.claude/trinity/sessions/` folder
+   - Completed work may exist in both `sessions/` AND their source directories (`work-orders/`, `investigations/`)
+   - The `plans/` directory is created by Claude Code during plan mode — always archive all contents
    - All reports are archived regardless of status
+   - Loose files in archive subdirectories should be organized into YYYY-MM-DD date folders
 
 2. **ALY analyzes session events:**
    - Review all work completed during session
@@ -87,6 +114,8 @@ End current Trinity Method session and prepare for commit.
    - Verify .claude/trinity/investigations/ contains only active investigations
    - Verify .claude/trinity/reports/ is empty
    - Verify .claude/trinity/sessions/ is empty
+   - Verify .claude/trinity/plans/ is empty
+   - Verify all files in .claude/trinity/archive/ subdirectories are in YYYY-MM-DD date folders
    - Ready for next session
 
 4. **Git commit instructions:**

package/dist/templates/.claude/commands/utility/trinity-workorder.md.template

@@ -32,6 +32,23 @@ Examples: WO-042-jwt-refresh-implementation.md
 
 ---
 
+## Work Order Numbering
+
+**To determine the next WO number:**
+
+1. Scan `.claude/trinity/work-orders/` for files matching `WO-*.md`
+2. Scan `.claude/trinity/sessions/` for files matching `WO-*.md`
+3. From all matches in those two directories, extract the highest `XXX` number
+4. New WO number = highest + 1 (zero-padded to 3 digits)
+5. If NO work orders are found in either directory, start at `WO-001`
+
+**IMPORTANT:**
+- Do **NOT** scan `.claude/trinity/archive/` — archived WOs belong to past sessions
+- Do **NOT** scan any other directories
+- Each new session with no active or pending WOs starts fresh at WO-001
+
+---
+
 ## Direct Work Order Creation
 
 When `/trinity-workorder` is invoked, the agent will:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trinity-method-sdk",
-  "version": "2.2.1",
+  "version": "2.2.2",
   "description": "Trinity Method SDK - Investigation-first development methodology for any project",
   "type": "module",
   "main": "dist/index.js",