@grunnverk/kodrdriv 1.3.0

package/dist/mcp/prompts/check_development.md

@@ -0,0 +1,169 @@
+# Check Development Readiness
+
+## Objective
+
+Verify that projects are ready for development work. This prompt provides a comprehensive check to ensure:
+1. No projects are on the main branch
+2. All repositories have pulled the latest changes from remote
+3. Packages are on dev tag versions locally
+4. Local packages are linked via `kodrdriv link` or `kodrdriv tree link`
+
+This is a quick verification step before starting development work to ensure you're working with the latest code and proper local dependencies.
+
+## Determining Tree vs Single-Package Operation
+
+**Important**: Before proceeding, determine if this is a tree operation or a single-package operation:
+
+- **Tree Operation**: If the directory (${directory}) contains subdirectories with `package.json` files, this is a monorepo/tree operation. Check all packages in the tree.
+- **Single-Package Operation**: If the directory is a leaf project (single package without subdirectories containing `package.json`), check only this single package.
+
+## Workflow Steps
+
+### For Tree Operations (Monorepo)
+
+1. **Check Branch Status**
+   - For each package in the tree, check the current git branch
+   - Use `git branch --show-current` or `getGitStatusSummary()` from `@grunnverk/git-tools` to get the current branch
+   - **Fail if any package is on `main` or `master` branch** - these should be on `working` or a feature branch
+   - Report which packages are on the wrong branch
+
+2. **Check Remote Sync Status**
+   - For each package, check if the local branch is up to date with remote
+   - Use `git fetch` first to update remote refs
+   - Compare local branch with `origin/{branch}` using `git rev-parse` or `git status`
+   - **Fail if any package is behind remote** - run `kodrdriv_tree_pull` to sync
+   - Report which packages need to pull changes
+
+3. **Check Dev Version Status**
+   - For each package, read `package.json` and check the version field
+   - Verify that versions contain a dev tag (e.g., `1.2.3-dev.0`, `0.5.1-dev.2`)
+   - Use `isDevelopmentVersion()` from `@grunnverk/core` if available, or check for patterns like `-dev.`, `-alpha`, `-beta`, `-rc`
+   - **Fail if any package has a non-dev version** (e.g., `1.2.3` without `-dev.0`) - this suggests the package needs `kodrdriv development` run
+   - Report which packages have incorrect version formats
+
+4. **Check Link Status**
+   - For each package, check if local dependencies are properly linked
+   - Use `getGloballyLinkedPackages()` and `getLinkedDependencies()` from `@grunnverk/git-tools` to check link status
+   - Alternatively, check `node_modules` for symlinks pointing to local packages
+   - Check `package.json` dependencies - if they reference scoped packages (e.g., `@grunnverk/*`), verify they're linked, not using registry versions
+   - **Fail if local dependencies are not linked** - run `kodrdriv_tree_link` to set up local links
+   - Report which packages need linking
+
+5. **Summary Report**
+   - Provide a clear summary of all checks
+   - List any failures with specific packages and what needs to be fixed
+   - If all checks pass, confirm that the project is ready for development
+
+### For Single-Package Operations (Leaf Project)
+
+1. **Check Branch Status**
+   - Check the current git branch using `git branch --show-current` or `getGitStatusSummary()`
+   - **Fail if on `main` or `master` branch** - should be on `working` or a feature branch
+   - Report the current branch
+
+2. **Check Remote Sync Status**
+   - Run `git fetch` to update remote refs
+   - Compare local branch with `origin/{branch}` using `git rev-parse` or `git status`
+   - **Fail if behind remote** - run `kodrdriv_pull` to sync
+   - Report sync status
+
+3. **Check Dev Version Status**
+   - Read `package.json` and check the version field
+   - Verify that version contains a dev tag (e.g., `1.2.3-dev.0`)
+   - **Fail if version is not a dev version** - run `kodrdriv development` to update
+   - Report the current version
+
+4. **Check Link Status**
+   - Check if local dependencies are properly linked
+   - Use `getLinkedDependencies()` from `@grunnverk/git-tools` to check link status
+   - Check `node_modules` for symlinks pointing to local packages
+   - Check `package.json` dependencies - if they reference scoped packages, verify they're linked
+   - **Fail if local dependencies are not linked** - run `kodrdriv link` to set up local links
+   - Report link status
+
+5. **Summary Report**
+   - Provide a clear summary of all checks
+   - List any failures and what needs to be fixed
+   - If all checks pass, confirm that the project is ready for development
+
+## Common Issues and Fixes
+
+### Issue: Package on main branch
+**Fix**: Switch to working branch or create a feature branch
+```bash
+git checkout working
+# or
+git checkout -b feature/my-feature
+```
+
+### Issue: Behind remote
+**Fix**: Pull latest changes
+```bash
+# For tree operations
+kodrdriv tree pull
+
+# For single package
+kodrdriv pull
+```
+
+### Issue: Not on dev version
+**Fix**: Run development command to bump to dev version
+```bash
+# For tree operations (if supported)
+kodrdriv development
+
+# For single package
+kodrdriv development
+```
+
+### Issue: Local dependencies not linked
+**Fix**: Run link command
+```bash
+# For tree operations
+kodrdriv tree link
+
+# For single package
+kodrdriv link
+```
+
+## Expected End State
+
+After all checks pass, you should have:
+- All packages on `working` or feature branches (not `main`)
+- All repositories synced with remote
+- All packages with dev versions (e.g., `1.2.3-dev.0`)
+- All local dependencies properly linked via `kodrdriv link`
+
+## Important Notes
+
+- **Branch Check**: The main branch check is critical - you should never develop directly on `main`
+- **Remote Sync**: Always ensure you have the latest changes before starting work
+- **Dev Versions**: Working branches should always have dev versions to distinguish from release versions
+- **Link Status**: Local development requires linking to test changes across packages
+- **Efficiency**: For large monorepos, checks can be done in parallel where possible
+
+## Example Output
+
+```
+✅ Branch Check: All packages on working branch
+✅ Remote Sync: All packages up to date with remote
+✅ Dev Versions: All packages have dev versions (e.g., 1.2.3-dev.0)
+✅ Link Status: All local dependencies properly linked
+
+Project is ready for development!
+```
+
+Or if issues are found:
+
+```
+❌ Branch Check: @grunnverk/core is on main branch
+⚠️  Remote Sync: @grunnverk/git-tools is 3 commits behind origin/working
+❌ Dev Versions: @grunnverk/core has version 1.2.3 (should be 1.2.3-dev.0)
+⚠️  Link Status: @grunnverk/commands-git is not linked locally
+
+Actions needed:
+1. Switch @grunnverk/core to working branch
+2. Run kodrdriv tree pull to sync @grunnverk/git-tools
+3. Run kodrdriv development in @grunnverk/core
+4. Run kodrdriv tree link to link local dependencies
+```

package/dist/mcp/prompts/dependency_update.md

@@ -0,0 +1,62 @@
+Update dependencies to the latest published versions from npmjs for configured scopes and the package's own scope.
+
+**CRITICAL RULES:**
+- NEVER update to dev-tagged versions (e.g., `-dev.0`, `-dev.1`, `-alpha`, `-beta`, `-rc`)
+- Projects should NEVER depend on dev versions - they should use `kodrdriv link` for local development
+- Only update to stable, published versions available on npmjs
+
+## Determining Tree vs Single-Package Operation
+
+**Important**: Before proceeding, determine if this is a tree operation or a single-package operation:
+
+- **Tree Operation**: If the current directory contains subdirectories with `package.json` files, this is a monorepo/tree operation. Use `kodrdriv_tree_updates` command.
+- **Single-Package Operation**: If the directory is a leaf project (single package without subdirectories containing `package.json`), this is NOT a tree operation. Use `kodrdriv_updates` command instead.
+
+**Workflow:**
+
+### For Tree Operations (Monorepo)
+
+1. Determine which scopes to update:
+   - Check configuration for `updates.scopes` or `publish.scopedDependencyUpdates`
+   - If the current package has a scope (e.g., `@grunnverk/my-package`), include that scope
+   - Use all configured scopes plus the package's own scope
+
+2. Run `kodrdriv_tree_updates`:
+   - This uses npm-check-updates to find latest versions matching the scope pattern across all packages in the tree
+   - Updates only packages published on npmjs (not dev versions)
+   - Updates dependencies, devDependencies, and peerDependencies sections
+
+3. After updates:
+   - Run `npm install` in each updated package to update package-lock.json
+   - Review changes to ensure no dev versions were introduced
+   - Run `kodrdriv_tree_precommit` to verify everything still works across the tree
+     - **Note**: If precommit fails due to coverage threshold issues and the project uses lcov format, consider using the `brennpunkt` MCP server tools to analyze coverage gaps and prioritize test improvements. Install brennpunkt as an MCP server with: `npx -y -p @redaksjon/brennpunkt brennpunkt-mcp`
+   - Commit the changes with `kodrdriv_tree_commit`
+
+### For Single-Package Operations (Leaf Project)
+
+1. Determine which scopes to update:
+   - Check configuration for `updates.scopes` or `publish.scopedDependencyUpdates`
+   - If the current package has a scope (e.g., `@grunnverk/my-package`), include that scope
+   - Use all configured scopes plus the package's own scope
+
+2. Run `kodrdriv_updates`:
+   - This uses npm-check-updates to find latest versions matching the scope pattern for the single package
+   - Updates only packages published on npmjs (not dev versions)
+   - Updates dependencies, devDependencies, and peerDependencies sections
+
+3. After updates:
+   - Run `npm install` to update package-lock.json
+   - Review changes to ensure no dev versions were introduced
+   - Run `kodrdriv_precommit` to verify everything still works
+     - **Note**: If precommit fails due to coverage threshold issues and the project uses lcov format, consider using the `brennpunkt` MCP server tools to analyze coverage gaps and prioritize test improvements. Install brennpunkt as an MCP server with: `npx -y -p @redaksjon/brennpunkt brennpunkt-mcp`
+   - Commit the changes with `kodrdriv_commit`
+
+**Example:**
+If package is `@grunnverk/my-package` and config has `scopedDependencyUpdates: ["@riotprompt"]`, update:
+- `@grunnverk/*` dependencies (package's own scope)
+- `@riotprompt/*` dependencies (configured scope)
+
+**Verification:**
+- Check that no dependencies were updated to versions containing `-dev`, `-alpha`, `-beta`, or `-rc`
+- If any dev versions are found, they should be removed and replaced with `kodrdriv link` workflow instead

package/dist/mcp/prompts/fix_and_commit.md

@@ -0,0 +1,53 @@
+# Fix and Commit Workflow
+
+## Objective
+
+Ensure that precommit checks pass successfully for a single package. When failures occur, understand the root cause, fix the issues, and iterate until all checks pass.
+
+## Workflow Steps
+
+1. **Run Precommit Check**
+   - Run `kodrdriv_precommit` with `fix=true` on the directory (${directory})
+   - This will execute precommit checks (linting, type checking, tests, build) for the single package
+
+2. **Handle Failures**
+   - If precommit fails, analyze the error output and fix the issues:
+     - For lint errors: Fix code style issues or disable specific rules with inline comments if justified
+     - For type errors: Fix TypeScript type issues
+     - For test failures: Update or fix tests to match new behavior
+     - For build failures: Fix compilation or bundling issues
+     - For coverage drops: Add tests to maintain coverage thresholds
+       - **Tip**: If the project uses lcov format for coverage reports and you're struggling with coverage thresholds, consider using the `brennpunkt` MCP server tools (e.g., `brennpunkt_get_priorities`, `brennpunkt_coverage_summary`, `brennpunkt_get_file_coverage`) to identify high-priority files and understand coverage gaps. Install brennpunkt as an MCP server with: `npx -y -p @redaksjon/brennpunkt brennpunkt-mcp`
+
+3. **Iterate Until Success**
+   - Re-run `kodrdriv_precommit` with `fix=true` after each fix until all checks pass
+
+4. **Commit Changes**
+   - Once precommit checks pass, commit the fixes using `kodrdriv_commit` with `sendit=true`
+   - The commit message will be automatically generated from the changes
+
+## Important Notes
+
+- **Fix Flag**: Use `fix=true` to enable auto-fixing where possible, but manual fixes may still be required
+- **Iterative Process**: Continue fixing and re-running precommit until all checks pass
+
+## Example Flow
+
+```
+1. kodrdriv_precommit({ directory: "/path/to/package", fix: true })
+   → Fails: TypeScript type error in src/index.ts:42
+
+2. Analyze error: TypeScript type error in src/index.ts:42
+   → Fix the type error
+
+3. kodrdriv_precommit({ directory: "/path/to/package", fix: true })
+   → Fails: Linting error in src/utils.ts:15
+
+4. Fix linting error
+
+5. kodrdriv_precommit({ directory: "/path/to/package", fix: true })
+   → All checks pass
+
+6. kodrdriv_commit({ directory: "/path/to/package", sendit: true })
+   → Commits all fixes
+```

package/dist/mcp/prompts/publish.md

@@ -0,0 +1,100 @@
+# Publish Workflow
+
+## Objective
+
+Execute a complete publishing workflow for a single package. Handle errors gracefully, fix issues as they arise, and resume appropriately.
+
+## Pre-Publish Verification
+
+Before running `kodrdriv_publish`, verify that `kodrdriv_precommit` works successfully.
+
+**Exception**: If `fix_and_commit` was just executed successfully, you can skip the precommit check and proceed directly to publish. The `fix_and_commit` workflow already ensures all precommit checks pass.
+
+## Publishing Workflow
+
+1. **Run Publish**
+   - Execute `kodrdriv_publish` with appropriate parameters
+   - The command will start generating output
+
+2. **Monitor for Errors**
+   - Watch for errors:
+     - **GitHub Actions/Workflows errors**: Build failures, test failures, or validation errors in Pull Requests
+     - **Git conflicts**: Merge conflicts or branch state issues
+     - **Precondition check failures**: Version conflicts, branch state issues, or dependency problems
+
+3. **Handle Pull Request Errors**
+   - If an error occurs during Pull Request validation:
+     - The error message will typically include a link to the failing PR or workflow
+     - Navigate to the provided link and investigate the build/test errors
+     - Fix the issues in the codebase
+       - **Tip**: If test failures are related to coverage thresholds and the project uses lcov format, consider using the `brennpunkt` MCP server tools (e.g., `brennpunkt_get_priorities`, `brennpunkt_coverage_summary`) to identify which files need test coverage improvements. Install brennpunkt as an MCP server with: `npx -y -p @redaksjon/brennpunkt brennpunkt-mcp`
+     - Commit and push the fixes
+     - Simply restart `kodrdriv_publish` - the system will automatically check if a Pull Request exists and resume appropriately
+     - **Note**: Single-package publish does not use the `continue` parameter
+
+4. **Handle Release Workflow Errors**
+   - If an error occurs while waiting for a Release Workflow:
+     - This indicates a more serious problem
+     - Ask the user how to proceed
+     - The system may be in an inconsistent state that requires manual intervention
+
+5. **Handle Precondition Check Failures**
+   - If precondition checks fail (version conflicts, branch state, etc.):
+     - Analyze the error message to understand what needs to be fixed
+     - Fix the underlying issues
+     - Re-run `kodrdriv_publish`
+
+## Error Resolution Strategy
+
+### When Errors Occur
+
+1. **Read the Error Message Carefully**
+   - Error messages typically indicate:
+     - What type of error occurred
+     - Where to look for more information (PR links, file paths, etc.)
+
+2. **Investigate the Root Cause**
+   - For GitHub workflow errors: Check the PR/workflow logs
+   - For Git errors: Check branch state, conflicts, or merge issues
+   - For precondition errors: Check version numbers, branch names, or dependency states
+
+3. **Fix the Issues**
+   - Make necessary code changes
+   - Fix version conflicts
+   - Resolve Git conflicts
+   - Update dependencies if needed
+
+4. **Commit and Push**
+   - Commit fixes with appropriate messages
+   - Push changes to trigger re-validation
+
+5. **Resume Appropriately**
+   - Simply restart `kodrdriv_publish` - the system will automatically detect existing PRs and resume appropriately
+
+## Expected End State
+
+After a successful publish workflow, the project should end up in a "working" branch with:
+- An incremented version number
+- A dev tag (e.g., `1.2.3-dev.0`)
+
+**Note**: This is information for verification purposes. The publish workflow handles versioning automatically - you don't need to manually manage versions or tags.
+
+## Important Notes
+
+- **Don't Skip Precommit**: Unless `fix_and_commit` was just run, always verify precommit checks pass before publishing.
+- **Error Links**: When GitHub errors occur, they often provide direct links to PRs or workflows - use these to understand what needs fixing.
+- **Resume Strategy**: Simply restart `kodrdriv_publish` - the system will automatically detect existing PRs and resume appropriately.
+
+## Example Flow
+
+```
+1. Run kodrdriv_precommit (unless fix_and_commit was just run)
+2. Run kodrdriv_publish
+   → Error: PR validation failed
+   → Link provided: https://github.com/org/repo/pull/456
+3. Investigate PR #456 → Find linting error
+4. Fix the linting error → Commit and push
+5. Run kodrdriv_publish again
+   → System detects existing PR and resumes appropriately
+6. Monitor for completion
+```

package/dist/mcp/prompts/tree_fix_and_commit.md

@@ -0,0 +1,102 @@
+# Tree Fix and Commit Workflow
+
+## Objective
+
+Ensure that precommit checks pass successfully across the entire monorepo tree. When failures occur, understand the root cause, fix the issues, and resume from the point of failure rather than restarting from the beginning.
+
+## Critical: Monorepo Root Directory
+
+**IMPORTANT**: The monorepo root directory is `/Users/tobrien/gitw/grunnverk`, NOT `/Users/tobrien/gitw/grunnverk/kodrdriv`.
+
+- `kodrdriv` is a subdirectory within the `grunnverk` monorepo
+- All tree commands MUST be run from the grunnverk root: `/Users/tobrien/gitw/grunnverk`
+- Never run tree commands from within the kodrdriv subdirectory
+- The `directory` parameter for all MCP tree commands should be `/Users/tobrien/gitw/grunnverk`
+
+## Workflow Steps
+
+1. **Initial Precommit Check**
+   - **ALWAYS use the MCP tool**: Run `kodrdriv_tree_precommit` with `fix=true`, `parallel=true`, and `directory="/Users/tobrien/gitw/grunnverk"`
+   - **CRITICAL: Use `parallel=true`** - This dramatically speeds up execution for large monorepos by running independent packages concurrently
+   - **DO NOT** fall back to manual command-line execution (`npx kodrdriv tree precommit`) unless the MCP tool is completely broken
+   - If the MCP tool fails, investigate the error message carefully - it will tell you which package failed and why
+   - This will execute precommit checks (linting, type checking, tests, build) across all packages, respecting dependency order even in parallel mode
+
+2. **Handle Failures**
+   - **If the MCP tool fails**: The error message will indicate which package failed (e.g., "Command failed in package @grunnverk/tree-execution")
+   - **DO NOT** switch to manual command-line execution - continue using the MCP tool with `start_from` parameter
+   - Carefully analyze the error output to understand:
+     - Which package failed
+     - What type of error occurred (lint error, type error, test failure, build failure)
+     - The specific files and lines involved
+   - Fix the issues in the failing package:
+     - For lint errors: Fix code style issues or disable specific rules with inline comments if justified
+     - For type errors: Fix TypeScript type issues
+     - For test failures: Update or fix tests to match new behavior
+     - For build failures: Fix compilation or bundling issues
+     - For coverage drops: Add tests to maintain coverage thresholds
+       - **Tip**: If the project uses lcov format for coverage reports and you're struggling with coverage thresholds, consider using the `brennpunkt` MCP server tools (e.g., `brennpunkt_get_priorities`, `brennpunkt_coverage_summary`, `brennpunkt_get_file_coverage`) to identify high-priority files and understand coverage gaps. Install brennpunkt as an MCP server with: `npx -y -p @redaksjon/brennpunkt brennpunkt-mcp`
+
+3. **Resume from Failure Point**
+   - After fixing issues, use `start_from` parameter to resume from the package that failed
+   - **ALWAYS include `parallel=true`** when resuming - it significantly reduces wait time
+   - This avoids re-running checks on packages that already passed, saving significant time in large projects
+   - Example: If package `@grunnverk/core` failed, run `kodrdriv_tree_precommit` with `start_from="@grunnverk/core"`, `parallel=true`, and `fix=true`
+   - The `start_from` parameter accepts either package name (e.g., `@grunnverk/core`) or directory name (e.g., `core`)
+
+4. **Iterate Until Success**
+   - Repeat steps 2-3 until all packages pass precommit checks
+   - Each iteration should resume from the last failing package
+
+5. **Commit Changes**
+   - Once all precommit checks pass, commit the fixes using `kodrdriv_tree_commit` with `sendit=true`
+   - The commit message will be automatically generated from the changes
+
+## Important Notes
+
+- **ALWAYS use MCP tools**: Use `kodrdriv_tree_precommit`, `kodrdriv_tree_commit`, etc. - do NOT fall back to manual command-line execution
+- **Monorepo Root**: Always use `directory="/Users/tobrien/gitw/grunnverk"` - kodrdriv is a subdirectory, not the root
+- **Parallel Execution**: **ALWAYS use `parallel=true`** - This is critical for large monorepos as it can reduce execution time from 20-30 minutes to 5-10 minutes by running independent packages concurrently
+- **Efficiency**: For large monorepos, always use `start_from` to resume from failures rather than restarting the entire process
+- **Dependency Order**: The tree commands process packages in dependency order, even in parallel mode - independent packages run concurrently while respecting dependencies
+- **Fix Flag**: Use `fix=true` to enable auto-fixing where possible, but manual fixes may still be required
+- **All Tree Commands Support `start_from`**: The `start_from` parameter works with all tree MCP commands (`kodrdriv_tree_precommit`, `kodrdriv_tree_publish`, `kodrdriv_tree_commit`, etc.)
+- **MCP Tool Failures**: If the MCP tool reports an error, investigate the error message - it contains the package name and failure reason. Continue using the MCP tool with `start_from` and `parallel=true` to resume from the failure point.
+
+## Example Flow
+
+```
+1. kodrdriv_tree_precommit({
+     directory: "/Users/tobrien/gitw/grunnverk",
+     fix: true,
+     parallel: true  // CRITICAL: Speeds up execution significantly
+   })
+   → Fails at package "@grunnverk/commands-git"
+   → Error: "Command failed in package @grunnverk/commands-git"
+
+2. Analyze error: TypeScript type error in src/git.ts:42
+   → Fix the type error in the commands-git package
+
+3. kodrdriv_tree_precommit({
+     directory: "/Users/tobrien/gitw/grunnverk",
+     fix: true,
+     parallel: true,  // ALWAYS include parallel=true
+     start_from: "commands-git"  // or "@grunnverk/commands-git"
+   })
+   → Continues from commands-git, may fail at next package
+
+4. Repeat until all pass (always using MCP tools with parallel=true, never manual commands)
+
+5. kodrdriv_tree_commit({
+     directory: "/Users/tobrien/gitw/grunnverk",
+     sendit: true
+   })
+   → Commits all fixes
+```
+
+## What NOT to Do
+
+- ❌ **DO NOT** run `npx kodrdriv tree precommit` manually from the command line
+- ❌ **DO NOT** use `/Users/tobrien/gitw/grunnverk/kodrdriv` as the directory - that's a subdirectory, not the root
+- ❌ **DO NOT** switch to manual execution if the MCP tool fails - investigate the error and use `start_from` to resume
+- ❌ **DO NOT** run commands from within the kodrdriv directory - always use the grunnverk root

package/dist/mcp/prompts/tree_publish.md

@@ -0,0 +1,118 @@
+# Tree Publish Workflow
+
+## Objective
+
+Execute a complete publishing workflow for a monorepo tree. Handle errors gracefully, fix issues as they arise, and resume from checkpoints when appropriate.
+
+## Pre-Publish Verification
+
+**Important**: Before running `kodrdriv_tree_publish`, verify that `kodrdriv_tree_precommit` works successfully.
+
+**CRITICAL: Use `parallel=true`** when running `kodrdriv_tree_precommit` - this dramatically speeds up execution for large monorepos (reduces time from 20-30 minutes to 5-10 minutes).
+
+**Exception**: If `tree_fix_and_commit` was just executed successfully, you can skip the precommit check and proceed directly to publish. The `tree_fix_and_commit` workflow already ensures all precommit checks pass.
+
+## Publishing Workflow
+
+**CRITICAL: Maintain Tree Publish Context**
+
+Once you start a `kodrdriv_tree_publish` operation, you establish a context file that facilitates coordinated version updates across all projects in the monorepo. **DO NOT switch between tree and single-package operations** during a publish workflow.
+
+- **If tree publish fails**: Fix the problem at the failing package, then return to the **top-level directory** and run `kodrdriv_tree_publish` with `continue: true`
+- **NEVER switch to `kodrdriv_publish`** in a subproject when recovering from a tree publish failure
+- The context file created by tree publish tracks version coordination across packages - switching to single-package publish breaks this coordination
+
+1. **Run Tree Publish**
+   - Execute `kodrdriv_tree_publish` with appropriate parameters
+   - If specific packages are provided (${packages}), use the `packages` parameter to target only those packages
+   - The command will start generating output as it processes packages in dependency order
+   - This creates a context file that tracks version updates across the entire tree
+
+2. **Monitor for Errors**
+   - Watch the output carefully for errors
+   - Common error sources:
+     - **GitHub Actions/Workflows**: Build failures, test failures, or validation errors in Pull Requests
+     - **Git Conflicts**: Merge conflicts or branch state issues
+     - **Precondition Checks**: Version conflicts, branch state issues, or dependency problems
+
+3. **Handle Pull Request Errors**
+   - If an error occurs during Pull Request validation:
+     - The error message will typically include a link to the failing PR or workflow
+     - Navigate to the provided link and investigate the build/test errors
+     - Fix the issues in the codebase
+       - **Tip**: If test failures are related to coverage thresholds and the project uses lcov format, consider using the `brennpunkt` MCP server tools (e.g., `brennpunkt_get_priorities`, `brennpunkt_coverage_summary`) to identify which files need test coverage improvements. Install brennpunkt as an MCP server with: `npx -y -p @redaksjon/brennpunkt brennpunkt-mcp`
+     - Commit and push the fixes
+     - Once the PR starts re-validating, use `kodrdriv_tree_publish` with `continue: true` to resume from the checkpoint
+     - **Important**: The `continue` parameter only works during the Pull Request wait phase
+
+4. **Handle Release Workflow Errors**
+   - If an error occurs while waiting for a Release Workflow:
+     - This indicates a more serious problem
+     - **Do NOT attempt to use `continue`** - ask the user how to proceed
+     - The system may be in an inconsistent state that requires manual intervention
+
+5. **Handle Precondition Check Failures**
+   - If precondition checks fail (version conflicts, branch state, etc.):
+     - Analyze the error message to understand what needs to be fixed
+     - Fix the underlying issues
+     - Re-run `kodrdriv_tree_publish` (you may need to use `continue: true` if a checkpoint exists)
+
+## Error Resolution Strategy
+
+### When Errors Occur
+
+1. **Read the Error Message Carefully**
+   - Error messages typically indicate:
+     - Which package failed
+     - What type of error occurred
+     - Where to look for more information (PR links, file paths, etc.)
+
+2. **Investigate the Root Cause**
+   - For GitHub workflow errors: Check the PR/workflow logs
+   - For Git errors: Check branch state, conflicts, or merge issues
+   - For precondition errors: Check version numbers, branch names, or dependency states
+
+3. **Fix the Issues**
+   - Make necessary code changes
+   - Fix version conflicts
+   - Resolve Git conflicts
+   - Update dependencies if needed
+
+4. **Commit and Push**
+   - Commit fixes with appropriate messages
+   - Push changes to trigger re-validation
+
+5. **Resume Appropriately**
+   - Return to the **top-level directory** and use `kodrdriv_tree_publish` with `continue: true` during PR wait phase
+     - **CRITICAL**: Do NOT switch to `kodrdriv_publish` in a subproject - this breaks the tree publish context
+
+## Expected End State
+
+After a successful publish workflow, projects should end up in a "working" branch with:
+- An incremented version number
+- A dev tag (e.g., `1.2.3-dev.0`)
+
+**Note**: This is information for verification purposes. The publish workflow handles versioning automatically - you don't need to manually manage versions or tags.
+
+## Important Notes
+
+- **Maintain Tree Publish Context**: Once you start `kodrdriv_tree_publish`, you establish a context file that coordinates version updates across projects. If tree publish fails, fix the issue and return to the top-level directory to run `kodrdriv_tree_publish` with `continue: true`. **NEVER switch to `kodrdriv_publish` in a subproject** - this breaks version coordination.
+- **Checkpoint Recovery**: The `continue` parameter only works during Pull Request validation waits. It does NOT work for Release Workflow errors.
+- **Don't Skip Precommit**: Unless `fix_and_commit` was just run, always verify precommit checks pass before publishing.
+- **Error Links**: When GitHub errors occur, they often provide direct links to PRs or workflows - use these to understand what needs fixing.
+- **Resume Strategy**: Use `continue: true` to resume from checkpoints at the **top-level directory**.
+
+## Example Flow
+
+```
+1. Run kodrdriv_tree_precommit({ parallel: true }) (unless fix_and_commit was just run)
+   → Use parallel=true to speed up execution significantly
+2. Run kodrdriv_tree_publish
+   → Error: PR validation failed for @org/package-a
+   → Link provided: https://github.com/org/repo/pull/123
+3. Investigate PR #123 → Find failing test
+4. Fix the test → Commit and push
+5. **Return to top-level directory** → Run kodrdriv_tree_publish({ continue: true })
+   → Resumes from checkpoint, continues processing with maintained context
+6. Monitor for additional errors or completion
+```