# 1. Check current state
git status
bd list --status open

# 2. Find or create an issue
bd list  # Show all issues
bd show <issue-id>  # View specific issue
bd create "Issue title" --type feature --priority medium  # Create if needed

# 3. Create branch from main
git checkout main
git pull origin main
git checkout -b feature/<issue-id>-<short-description>

# 4. Ensure go.work exists and is NOT staged
mise run dev-setup  # or manually create go.work if needed

# 5. Start development
bd update <issue-id> --status in-progress

# Automatically discover and configure all modules
bash ./scripts/setup-workspace.sh   # Linux/macOS
# or
pwsh ./scripts/setup-workspace.ps1  # Windows

# Check if go.work exists
if [ ! -f go.work ]; then
    echo "Creating go.work for local development..."
    go work init
    go work use ./cmd/morphir
    go work use ./pkg/bindings/typemap
    go work use ./pkg/bindings/wit
    go work use ./pkg/config
    go work use ./pkg/docling-doc
    go work use ./pkg/models
    go work use ./pkg/nbformat
    go work use ./pkg/pipeline
    go work use ./pkg/sdk
    go work use ./pkg/task
    go work use ./pkg/tooling
    go work use ./pkg/vfs
    go work use ./tests/bdd
fi

# Verify go.work is in .gitignore
grep -q "go.work" .gitignore || echo "⚠️  WARNING: go.work should be in .gitignore!"

# Ensure go.work is not staged
git status --short | grep "go.work" && echo "⚠️  WARNING: go.work is staged! Run: git reset go.work"

# 1. Go version
go version  # Should be 1.25.5 or later

# 2. Required tools
command -v goreleaser || echo "Install: go install github.com/goreleaser/goreleaser/v2@latest"
command -v gh || echo "Install GitHub CLI: https://cli.github.com/"
command -v mise || echo "Install mise: https://mise.jdx.dev/"
command -v bd || echo "Install beads: npm install -g @beads/cli"

# 3. Git configuration
git config user.name || echo "Set: git config user.name 'Your Name'"
git config user.email || echo "Set: git config user.email 'your.email@example.com'"

# 4. Workspace verification
mise run verify  # All modules should build

# 1. Write tests first (in tests/bdd or package-level tests)
# 2. Run tests (they should fail)
mise run test
# This runs the workspace doctor first to apply local fixes.

# 3. Implement functionality
# 4. Run tests again (they should pass)
mise run test
# This runs the workspace doctor first to apply local fixes.

# 5. Refactor while keeping tests green

# Work on a specific module
cd pkg/tooling
go test ./...
go build ./...

# Workspace handles module resolution automatically via go.work
# NO need for replace directives!

# 1. Verify no replace directives (CRITICAL!)
grep -r "^replace " --include="go.mod" . && echo "❌ FAIL: Replace directives found!" || echo "✅ PASS: No replace directives"

# 2. Verify go.work not staged
git status --short | grep "go.work" && echo "❌ FAIL: go.work is staged!" || echo "✅ PASS: go.work not staged"

# 3. Format code
mise run fmt

# 4. Run linters
mise run lint

# 5. Build all modules
mise run verify

# 6. Run tests
mise run test

# 7. Verify schema sync (if schema files changed)
if git diff --cached --name-only | grep -q "schemas/"; then
    python .claude/skills/morphir-developer/scripts/convert_schema.py --verify website/static/schemas/ || echo "❌ FAIL: Schema files out of sync!"
fi

# 8. Check for uncommitted changes in tracked files
git status --short

# 1. Stage changes
git add <files>

# 2. Commit with conventional commit message
git commit -m "feat: add feature description

Detailed explanation of changes.

Closes: <issue-id>"

# 3. Push branch
git push -u origin feature/<issue-id>-description

# 4. Create PR
gh pr create --title "feat: feature description" --body "Closes #<issue-number>"

# 5. Update beads issue
bd update <issue-id> --status in-review

# Create worktree for new feature
git worktree add ../morphir-feature-x feature/issue-123-feature-x

# Each worktree needs its own go.work
cd ../morphir-feature-x
mise run dev-setup  # Creates go.work in this worktree

# When done, remove worktree
cd ../morphir
git worktree remove ../morphir-feature-x

# go.work automatically uses local versions, no action needed!
# Just rebuild
mise run verify

# 1. Create module
mkdir -p pkg/newmodule
cd pkg/newmodule
go mod init github.com/finos/morphir/pkg/newmodule

# 2. Add to go.work
go work use ./pkg/newmodule

# 3. Add to build scripts (scripts/release-prep.sh, .goreleaser.yaml)

# 4. Set up coverage tracking
mise run setup-coverage  # Discovers and verifies all modules

# 5. Update test-junit.sh MODULES array if needed (for JUnit reports)

# 6. Update documentation

# 7. Verify
mise run verify

# Run tests with full coverage report
mise run test-junit

# This generates:
# - test-results/*.xml   (JUnit test reports)
# - coverage/*.out       (Per-module coverage profiles)
# - coverage.out         (Merged coverage profile)

# View coverage summary
go tool cover -func=coverage.out | tail -1

# View detailed coverage by function
go tool cover -func=coverage.out

# Generate HTML coverage report (opens in browser)
go tool cover -html=coverage.out -o coverage.html
open coverage.html  # macOS
# xdg-open coverage.html  # Linux

# Run coverage for a single module
cd pkg/pipeline
go test -coverprofile=coverage.out -covermode=atomic ./...
go tool cover -func=coverage.out

# Run coverage with race detection
go test -race -coverprofile=coverage.out -covermode=atomic ./...

# Discover all modules and verify coverage works
mise run setup-coverage

# Check only (don't run tests)
mise run setup-coverage -- --check

# List all discoverable modules
mise run setup-coverage -- --list

# The coverage summary shows:
go tool cover -func=coverage.out
# github.com/finos/morphir/pkg/pipeline/pipeline.go:42:  NewPipeline  100.0%
# github.com/finos/morphir/pkg/pipeline/pipeline.go:58:  Run          85.7%
# total:                                                 (statements) 55.0%

# What the numbers mean:
# - 100.0% = All statements in function are covered
# - 85.7%  = Most statements covered, some branches missing
# - 0.0%   = No tests cover this function (needs attention!)

# Convert YAML schemas to JSON
python .claude/skills/morphir-developer/scripts/convert_schema.py website/static/schemas/

# Verify YAML and JSON are in sync
python .claude/skills/morphir-developer/scripts/convert_schema.py --verify website/static/schemas/

# Check for drift between schema and Go implementation
python .claude/skills/morphir-developer/scripts/check_schema_drift.py --all

# JSON output for CI
python .claude/skills/morphir-developer/scripts/check_schema_drift.py --all --json

# Add to pre-commit workflow
echo "Checking schema sync..."
python .claude/skills/morphir-developer/scripts/convert_schema.py --verify website/static/schemas/ || {
    echo "❌ FAIL: Schema YAML/JSON out of sync!"
    echo "Run: python .claude/skills/morphir-developer/scripts/convert_schema.py website/static/schemas/"
    exit 1
}

echo "Checking schema-code drift..."
python .claude/skills/morphir-developer/scripts/check_schema_drift.py --sync

Question: I noticed a new type `{TypeName}` in the Go model that's not documented in the IR schema.

Options:
1. "Add to schema" - Create a beads issue to update the schema
2. "Intentional" - This type is internal and shouldn't be in the public schema
3. "Already planned" - Schema update is already tracked elsewhere

Question: The schema defines `{TypeName}` but I couldn't find a corresponding Go implementation.

Options:
1. "Implementation needed" - Create a beads issue to implement the type
2. "Different name" - The Go type uses a different naming convention
3. "Embedded" - This type is embedded in another Go struct

# Create beads issue for schema update
bd create --title "Update IR schema: add {TypeName}" --type task --priority 2

# Or create GitHub issue for public tracking
gh issue create --title "Schema drift: {TypeName}" --body "Schema and implementation are out of sync..."

# 1. Check go.work exists and has all modules
cat go.work

# 2. Sync workspace
go work sync

# 3. Verify module list
go work use -r .  # Add all modules recursively

# 4. Check module graph
go mod graph

# 5. Clean and rebuild
go clean -modcache
mise run verify

# List issues
bd list
bd list --status open
bd list --priority high
bd blocked  # Show blocked issues
bd ready    # Show ready-to-work issues

# View issue details
bd show <issue-id>

# Create issue
bd create "Feature: Add new functionality" --type feature --priority medium

# Update issue status
bd update <issue-id> --status in-progress
bd update <issue-id> --status completed

# Add comments
bd comments <issue-id> add "Working on implementation"

# Create dependencies
bd dep add <issue-id> <depends-on-id>

# Search issues
bd search "keyword"

# List issues
gh issue list
gh issue list --label "good first issue"

# View issue
gh issue view <issue-number>

# Create issue
gh issue create --title "Bug: Description" --body "Details"

# Close issue
gh issue close <issue-number>

# Link PR to issue (in PR description)
# Use: "Closes #<issue-number>" or "Fixes #<issue-number>"

# List available fixtures
python .claude/skills/morphir-developer/scripts/fetch_morphir_ir.py --list

# Download the rentals fixture (latest version)
python .claude/skills/morphir-developer/scripts/fetch_morphir_ir.py --fixture rentals

# Download specific version
python .claude/skills/morphir-developer/scripts/fetch_morphir_ir.py --fixture rentals --version v2.100.0

# Download to specific directory
python .claude/skills/morphir-developer/scripts/fetch_morphir_ir.py --fixture rentals --output ./tests/bdd/testdata/fixtures

# Download all fixtures
python .claude/skills/morphir-developer/scripts/fetch_morphir_ir.py --all --output ./fixtures

# List cached fixtures
python .claude/skills/morphir-developer/scripts/fetch_morphir_ir.py --cached

# Clear cache
python .claude/skills/morphir-developer/scripts/fetch_morphir_ir.py --clear-cache

# List available fixtures
mise run fixtures:list

# Fetch all fixtures to tests/bdd/testdata/morphir-ir
mise run fixtures:fetch

# Fetch just the rentals fixture
mise run fixtures:fetch:rentals

# Fetch fixtures from a specific version
MORPHIR_VERSION=v2.100.0 mise run fixtures:fetch:version

// In Go tests, fixtures can be loaded from the testdata directory
import "github.com/finos/morphir/tests/bdd/testdata"

func TestWithFixture(t *testing.T) {
    irData, err := testdata.LoadFixture("rentals.json")
    if err != nil {
        t.Fatalf("Failed to load fixture: %v", err)
    }
    // Use irData...
}

# 1. Ensure go.work exists
ls go.work || mise run dev-setup

# 2. Verify module is in go.work
grep "pkg/xxx" go.work || go work use ./pkg/xxx

# 3. Sync workspace
go work sync

# 4. Clean and rebuild
go clean -modcache
mise run verify

# Remove all replace directives
bash ./scripts/remove-replace-directives.sh

# Ensure go.work exists for local development
mise run dev-setup

# Verify modules still build
mise run verify

# Confirm workspace is active
go env GOWORK

# Ensure all modules are included
go work use -r .
go work edit -print

# Sync workspace
go work sync

# From repo root, GOMOD should be /dev/null when workspace is active
go env GOMOD

# If GOWORK is empty, set it for the command
GOWORK="$(git rev-parse --show-toplevel)/go.work" go test ./cmd/morphir/...

# Or run the workspace doctor (interactive, default uses versioned go.work replaces)
mise run workspace-doctor

# Verify no replace directives exist
rg -n "^replace " --glob "*/go.mod"

# Ensure workspace files are not staged
git status --short | rg "go.work"

# If errors still mention unknown revision pkg/.../vX.Y.Z:
# - Ensure the dependency version exists as a tag, or
# - Avoid adding the dependency until a release tag exists.
#
# go.work use does not override invalid version references in go.mod.
# Local-only workaround:
#   go work edit -replace=github.com/finos/morphir/pkg/<module>@vX.Y.Z=./pkg/<module>
#
# If using git worktrees, each worktree needs its own go.work.
#
# Avoid go.work replace directives unless absolutely necessary; they must be version-qualified.
#
# Optional cache reset after repeated attempts:
# go clean -cache -modcache

# Unstage go.work files
git reset go.work go.work.sum

# Ensure in .gitignore
grep "go.work" .gitignore || echo "go.work\ngo.work.sum" >> .gitignore

# Never commit workspace files!

# Start of day
git checkout main && git pull
bd ready  # Find work to do

# During development
mise run verify  # Build everything
mise run test    # Run all tests
mise run fmt     # Format code
mise run lint    # Run linters

# Before commit
mise run ci-check  # Run all checks
git status        # Review changes

# End of day
bd list --status in-progress  # Review work in progress
git push      # Push branches

⚠️ PRINCIPLE VIOLATION: This struct uses a 'kind' field pattern instead of typestate.
   See AGENTS.md "Making Illegal States Unrepresentable" for the preferred approach.
   If this is intentional, please add an exception comment explaining why.

⚠️ PRINCIPLE VIOLATION: This function mutates its input instead of returning a new value.
   Consider using functional update pattern. If mutation is required for performance,
   add an exception comment explaining the trade-off.

// EXCEPTION: Using tagged struct instead of typestate pattern.
// Reason: This type is only used for JSON serialization and the schema
// requires a discriminator field. The internal types use proper typestate.
// See: https://github.com/finos/morphir/issues/XXX
type SerializedTask struct {
    Kind   string `json:"kind"`
    // ...
}

// EXCEPTION: Mutable state for performance.
// Reason: This buffer is reused across iterations to avoid allocations
// in a hot path. Benchmarks show 3x improvement.
// See: pkg/pipeline/benchmark_test.go
type StreamProcessor struct {
    buffer []byte // mutable, reused
}

# Check for potential principle violations
echo "Checking for tagged struct patterns..."
grep -rn "Kind.*TaskKind\|Type.*string.*//.*kind\|kind.*=.*\"" --include="*.go" pkg/ cmd/ | grep -v "_test.go" | grep -v "EXCEPTION:" && echo "⚠️  Review: Possible tagged struct pattern found"

echo "Checking for undocumented exceptions..."
grep -rn "EXCEPTION:" --include="*.go" pkg/ cmd/ | while read line; do
    echo "📝 Exception found: $line"
done

# Run schema drift detection
python .claude/skills/morphir-developer/scripts/check_schema_drift.py --all

# If drift detected, use AskUserQuestion to determine action:
# - Request code changes to sync
# - Create beads issue for future work
# - Create GitHub issue for public tracking

# Run pre-release validation
./scripts/release-validate.sh v0.4.0-alpha.1

# Check with JSON output for automation
./scripts/release-validate.sh --json v0.4.0-alpha.1 | jq '.checks[] | select(.status == "error")'

# Preview what tags would be created (safe, non-destructive)
./scripts/release-tags.sh --dry-run create v0.4.0-alpha.1

# List existing tags for a version
./scripts/release-tags.sh list v0.4.0-alpha.1

# Create tags locally (after validation passes)
./scripts/release-tags.sh create v0.4.0-alpha.1

# Verify the release
./scripts/release-verify.sh v0.4.0-alpha.1

# Skip go install test for faster verification
./scripts/release-verify.sh --skip-install v0.4.0-alpha.1

# JSON output for CI integration
./scripts/release-verify.sh --json v0.4.0-alpha.1

# ❌ WRONG - External consumption test will fail
require (
    github.com/finos/morphir/pkg/config v0.3.2  // Doesn't exist yet!
)

# ✅ CORRECT - External consumption test passes
require (
    github.com/finos/morphir/pkg/config v0.3.1  // Current released version
)