/working-tree:status

Display current worktree AI context metadata and git information.

EXECUTION PROTOCOL

Execute steps sequentially. Each step must complete successfully before proceeding.

STEP 1: DETECT REPOSITORY ROOT

EXECUTE:

REPO_ROOT=$(git rev-parse --show-toplevel 2>&1)
EXIT_CODE=$?

VALIDATION:

• IF EXIT_CODE != 0 → ERROR PATTERN "not-in-git-repo"
• REPO_ROOT must be absolute path starting with /
• REPO_ROOT directory must exist

DATA EXTRACTION:

• REPO_NAME = basename of REPO_ROOT

NEXT:

• On success → STEP 2
• On failure → ABORT

STEP 2: DETECT CURRENT BRANCH

EXECUTE:

BRANCH_NAME=$(git rev-parse --abbrev-ref HEAD 2>&1)
EXIT_CODE=$?

VALIDATION:

• IF EXIT_CODE != 0 → ERROR PATTERN "git-command-failed"
• BRANCH_NAME must not be empty string

NEXT:

• On success → STEP 3
• On failure → ABORT

STEP 3: CHECK METADATA FILE

EXECUTE:

METADATA_PATH="$REPO_ROOT/.ai-context.json"
test -f "$METADATA_PATH"
EXISTS=$?

VALIDATION:

• EXISTS is 0 (true) or 1 (false), no other values

NEXT:

• IF EXISTS == 0 → STEP 4 (metadata exists)
• IF EXISTS == 1 → STEP 5 (no metadata)

STEP 4: READ AND PARSE METADATA

EXECUTE:

METADATA_JSON=$(cat "$METADATA_PATH" 2>&1)
CAT_EXIT=$?

VALIDATION:

• IF CAT_EXIT != 0 → ERROR PATTERN "file-read-failed"

DATA EXTRACTION:

MODE=$(echo "$METADATA_JSON" | jq -r '.mode // "unknown"' 2>&1)
JQ_EXIT_MODE=$?
DESCRIPTION=$(echo "$METADATA_JSON" | jq -r '.description // ""' 2>&1)
JQ_EXIT_DESC=$?
CREATED=$(echo "$METADATA_JSON" | jq -r '.created // ""' 2>&1)
JQ_EXIT_CREATED=$?

VALIDATION:

• IF JQ_EXIT_MODE != 0 → ERROR PATTERN "invalid-json"
• MODE must be one of: main, feature, bugfix, experiment, review, unknown
• DESCRIPTION can be empty string
• CREATED should be ISO8601 format or empty

NEXT:

• On success → STEP 6 (display with metadata)
• On jq failure → ERROR PATTERN "invalid-json"

STEP 5: DISPLAY NO METADATA

OUTPUT FORMAT (exact):

Worktree Status
═══════════════════════════════════════════════════════════

Directory:    {REPO_NAME}
Branch:       {BRANCH_NAME}
Mode:         (no metadata)

⚠ No .ai-context.json found

This worktree doesn't have AI context metadata.

To add metadata to this worktree:
  /working-tree:adopt [--mode <mode>] [--description "<text>"]

To create a new worktree with metadata:
  /working-tree:new <branch-name>

NEXT:

• TERMINATE (success)

STEP 6: DISPLAY WITH METADATA

OUTPUT FORMAT (exact):

Worktree Status
═══════════════════════════════════════════════════════════

Directory:    {REPO_NAME}
Branch:       {BRANCH_NAME}
Mode:         {MODE}
Created:      {CREATED}

Purpose:
{DESCRIPTION or "No description provided"}

───────────────────────────────────────────────────────────

Mode Semantics:
  main       → Minimal changes, stable work only
  feature    → Active development, larger changes allowed
  bugfix     → Isolated, surgical fixes only
  experiment → Prototypes, large swings, unsafe changes allowed
  review     → Documentation, analysis, audits

Metadata file: .ai-context.json

TEMPLATE SUBSTITUTIONS:

• {REPO_NAME} = extracted from STEP 1
• {BRANCH_NAME} = extracted from STEP 2
• {MODE} = extracted from STEP 4
• {CREATED} = extracted from STEP 4
• {DESCRIPTION} = extracted from STEP 4, if empty use "No description provided"

NEXT:

• TERMINATE (success)

ERROR PATTERNS

PATTERN: not-in-git-repo

DETECTION:

• TRIGGER: git rev-parse --show-toplevel exit code != 0
• INDICATORS: stderr contains "not a git repository" OR "not inside a work tree"

RESPONSE (exact):

Error: Not in a git repository

Run this command from within a git repository.

CONTROL FLOW:

• ABORT: true
• RETRY: false
• FALLBACK: None

PATTERN: git-command-failed

DETECTION:

• TRIGGER: git command exit code != 0 (excluding rev-parse --show-toplevel which uses "not-in-git-repo")
• CAPTURE: stderr from failed git command

RESPONSE (exact):

Error: Failed to read git information

Git error: {GIT_STDERR}

Check that:
  - You're in a git repository
  - Git is installed and working

TEMPLATE SUBSTITUTIONS:

• {GIT_STDERR} = captured stderr from failed command

CONTROL FLOW:

• ABORT: true
• RETRY: false
• FALLBACK: None

PATTERN: invalid-json

DETECTION:

• TRIGGER: jq command exit code != 0 when parsing .ai-context.json
• CAPTURE: jq error message from stderr

RESPONSE (exact):

Warning: .ai-context.json exists but is invalid

JSON error: {JQ_ERROR}

The metadata file may be corrupted. Consider:
  - Fixing the JSON manually
  - Running /working-tree:adopt to regenerate

TEMPLATE SUBSTITUTIONS:

• {JQ_ERROR} = captured stderr from jq

CONTROL FLOW:

• ABORT: false (warning, not error)
• RETRY: false
• FALLBACK: STEP 5 (display as if no metadata)

PATTERN: file-read-failed

DETECTION:

• TRIGGER: cat command on .ai-context.json fails despite file existence check passing
• CAPTURE: stderr from cat command

RESPONSE (exact):

Error: Failed to read .ai-context.json

Read error: {CAT_ERROR}

Check file permissions on .ai-context.json

TEMPLATE SUBSTITUTIONS:

• {CAT_ERROR} = captured stderr from cat

CONTROL FLOW:

• ABORT: true
• RETRY: false
• FALLBACK: None

TOOL PERMISSION MATRIX

Tool	Pattern	Permission	Pre-Check	Post-Check	On-Deny-Action
Bash	git:*	ALLOW	command_safe	validate_output	N/A
Bash	jq:*	ALLOW	command_safe	validate_json	N/A
Bash	cat .ai-context.json	ALLOW	file_exists	validate_output	N/A
Bash	test:*	ALLOW	N/A	N/A	N/A
Bash	rm:*	DENY	N/A	N/A	ABORT "Destructive operation"
Bash	sudo:*	DENY	N/A	N/A	ABORT "Elevated privileges"
Read	.ai-context.json	ALLOW	file_exists	valid_json	N/A
Write	**	DENY	N/A	N/A	ABORT "Status is read-only"
Edit	**	DENY	N/A	N/A	ABORT "Status is read-only"

SECURITY CONSTRAINTS:

• This command is READ-ONLY
• NO file modifications allowed
• NO destructive operations allowed
• Git commands limited to read operations (rev-parse, status, etc.)

TEST CASES

TC001: Worktree with valid metadata

PRECONDITIONS:

• In git repository at /path/to/myapp
• Current branch: feature/login-refactor
• File exists: /path/to/myapp/.ai-context.json
• File contains valid JSON:

{
  "mode": "feature",
  "description": "Refactor authentication flow to support OAuth2",
  "created": "2025-11-23T10:30:00Z",
  "branch": "feature/login-refactor"
}

EXPECTED EXECUTION FLOW:

1. STEP 1 → REPO_ROOT="/path/to/myapp", REPO_NAME="myapp"
2. STEP 2 → BRANCH_NAME="feature/login-refactor"
3. STEP 3 → EXISTS=0 (metadata exists)
4. STEP 4 → MODE="feature", DESCRIPTION="Refactor authentication flow to support OAuth2", CREATED="2025-11-23T10:30:00Z"
5. STEP 6 → Display formatted output

EXPECTED OUTPUT:

Worktree Status
═══════════════════════════════════════════════════════════

Directory:    myapp
Branch:       feature/login-refactor
Mode:         feature
Created:      2025-11-23T10:30:00Z

Purpose:
Refactor authentication flow to support OAuth2

───────────────────────────────────────────────────────────

Mode Semantics:
  main       → Minimal changes, stable work only
  feature    → Active development, larger changes allowed
  bugfix     → Isolated, surgical fixes only
  experiment → Prototypes, large swings, unsafe changes allowed
  review     → Documentation, analysis, audits

Metadata file: .ai-context.json

VALIDATION COMMANDS:

# Verify file exists
test -f /path/to/myapp/.ai-context.json && echo "PASS" || echo "FAIL"

# Verify valid JSON
jq empty /path/to/myapp/.ai-context.json && echo "PASS" || echo "FAIL"

# Verify mode field
test "$(jq -r '.mode' /path/to/myapp/.ai-context.json)" = "feature" && echo "PASS" || echo "FAIL"

TC002: Worktree without metadata

PRECONDITIONS:

• In git repository at /path/to/myapp
• Current branch: main
• File does NOT exist: /path/to/myapp/.ai-context.json

EXPECTED EXECUTION FLOW:

1. STEP 1 → REPO_ROOT="/path/to/myapp", REPO_NAME="myapp"
2. STEP 2 → BRANCH_NAME="main"
3. STEP 3 → EXISTS=1 (no metadata)
4. STEP 5 → Display no-metadata output
5. TERMINATE

EXPECTED OUTPUT:

Worktree Status
═══════════════════════════════════════════════════════════

Directory:    myapp
Branch:       main
Mode:         (no metadata)

⚠ No .ai-context.json found

This worktree doesn't have AI context metadata.

To add metadata to this worktree:
  /working-tree:adopt [--mode <mode>] [--description "<text>"]

To create a new worktree with metadata:
  /working-tree:new <branch-name>

VALIDATION COMMANDS:

# Verify file does not exist
test ! -f /path/to/myapp/.ai-context.json && echo "PASS" || echo "FAIL"

TC003: Invalid JSON in metadata file

PRECONDITIONS:

• In git repository at /path/to/myapp
• Current branch: feature/test
• File exists: /path/to/myapp/.ai-context.json
• File contains invalid JSON: {invalid json}

EXPECTED EXECUTION FLOW:

1. STEP 1 → REPO_ROOT="/path/to/myapp"
2. STEP 2 → BRANCH_NAME="feature/test"
3. STEP 3 → EXISTS=0
4. STEP 4 → jq fails with parse error
5. ERROR PATTERN "invalid-json" → Warning displayed
6. FALLBACK → STEP 5 (display as no metadata)

EXPECTED OUTPUT:

Warning: .ai-context.json exists but is invalid

JSON error: parse error: Invalid numeric literal at line 1, column 10

The metadata file may be corrupted. Consider:
  - Fixing the JSON manually
  - Running /working-tree:adopt to regenerate

Worktree Status
═══════════════════════════════════════════════════════════

Directory:    myapp
Branch:       feature/test
Mode:         (no metadata)

⚠ No .ai-context.json found

This worktree doesn't have AI context metadata.

To add metadata to this worktree:
  /working-tree:adopt [--mode <mode>] [--description "<text>"]

To create a new worktree with metadata:
  /working-tree:new <branch-name>

VALIDATION COMMANDS:

# Verify file exists but is invalid
test -f /path/to/myapp/.ai-context.json && echo "EXISTS"
jq empty /path/to/myapp/.ai-context.json 2>&1 | grep -q "parse error" && echo "INVALID"

TC004: Not in git repository

PRECONDITIONS:

• Current directory: /tmp (not a git repository)

EXPECTED EXECUTION FLOW:

1. STEP 1 → git rev-parse fails with exit code 128
2. ERROR PATTERN "not-in-git-repo" triggered
3. ABORT

EXPECTED OUTPUT:

Error: Not in a git repository

Run this command from within a git repository.

VALIDATION COMMANDS:

# Verify not in git repo
cd /tmp
git rev-parse --show-toplevel 2>&1 | grep -q "not a git repository" && echo "PASS" || echo "FAIL"

RELATED COMMANDS

• /working-tree:adopt - Add metadata to current worktree
• /working-tree:new - Create new worktree with metadata
• /working-tree:list - List all worktrees with metadata
• /working-tree:destroy - Remove worktree safely

DELEGATION

For complex worktree strategy questions or multi-worktree workflows:

Task(
  subagent_type='working-tree-consultant',
  description='Worktree strategy consultation',
  prompt='[detailed question about worktree organization]'
)