Ground File Management

Reference for: Common Ground Load when: Storage operations, project identification, file format

---

Directory Structure

Ground files are stored in the user's Claude home directory:

~/.claude/common-ground/
├── index.md                              # Global registry of all projects
└── {project-id}/
    ├── COMMON-GROUND.md                         # Human-readable assumptions
    ├── ground.index.json                 # Machine-readable index
    └── archive/
        └── {timestamp}-{reason}.md       # Archived versions (future)

---

Project Identification

Primary Method: Git Remote

git remote get-url origin 2>/dev/null

Example outputs:

• https://github.com/user/repo.git -> project_id: github.com/user/repo
• git@github.com:user/repo.git -> project_id: github.com/user/repo

Normalization rules:

1. Remove protocol prefix (https://, git@)
2. Remove .git suffix
3. Replace : with / for SSH URLs
4. Use as directory name (URL-safe characters)

Fallback Method: Path-Based

If no git remote found:

pwd

Example:

• /home/user/projects/my-app -> project_id: local/home-user-projects-my-app

Normalization rules:

1. Prefix with local/
2. Replace / with -
3. Remove leading slash

---

Global Index (index.md)

Located at: ~/.claude/common-ground/index.md

Template

# Common Ground: Project Registry

Last Updated: {timestamp}

## Tracked Projects

| Project | ID | Assumptions | Last Check |
|---------|----|-----------:|------------|
| {name} | {project_id} | {count} | {date} |

---

*Auto-generated by /common-ground command*

Update Rules

• Add new project when first ground file created
• Update counts and dates on each /common-ground run
• Remove projects when ground file deleted (future --reset)

---

Ground File (COMMON-GROUND.md)

Located at: ~/.claude/common-ground/{project_id}/COMMON-GROUND.md

Template

# Project Common Ground

**Project:** {project_name}
**Project ID:** {project_id}
**Created:** {created_timestamp}
**Last Updated:** {updated_timestamp}

---

## ESTABLISHED

High confidence assumptions. Treat as premises.

### {id}: {title}

- **Type:** {stated|inferred|assumed}
- **Assumption:** {description}
- **Source:** {evidence or citation}
- **Validated:** {date}
- **Context:** {when this applies}

---

## WORKING

Medium confidence. Use but flag if contradicted.

### {id}: {title}

- **Type:** {stated|inferred|assumed}
- **Assumption:** {description}
- **Source:** {evidence or citation}
- **Validated:** {date}
- **Context:** {when this applies}

---

## OPEN

Low confidence. Ask before assuming.

### {id}: {title}

- **Type:** {stated|inferred|assumed|uncertain}
- **Assumption:** {description}
- **Source:** {evidence or citation}
- **Validated:** {date}
- **Context:** {when this applies}

---

## History

| Date | Action | ID | Details |
|------|--------|------|---------|
| {date} | {Created/Promoted/Demoted/Archived} | {id} | {details} |

---

*Managed by /common-ground command*

Assumption ID Format

Format: A{number} (e.g., A001, A002, A003)

• Sequential within project
• Never reused (even after archival)
• Track highest ID in index.json

---

Machine Index (ground.index.json)

Located at: ~/.claude/common-ground/{project_id}/ground.index.json

Schema

{
  "version": "1.0",
  "project_id": "{project_id}",
  "project_name": "{human_readable_name}",
  "created": "{ISO_timestamp}",
  "last_updated": "{ISO_timestamp}",
  "next_id": 4,
  "assumptions": [
    {
      "id": "A001",
      "title": "{short_title}",
      "type": "stated|inferred|assumed|uncertain",
      "tier": "ESTABLISHED|WORKING|OPEN",
      "assumption": "{full_description}",
      "source": "{evidence}",
      "validated": "{ISO_date}",
      "context": "{when_applies}",
      "created": "{ISO_timestamp}",
      "history": [
        {
          "date": "{ISO_timestamp}",
          "action": "created|promoted|demoted",
          "from_tier": null,
          "to_tier": "WORKING",
          "reason": "{optional}"
        }
      ]
    }
  ],
  "archived": []
}

Field Definitions

Field	Type	Description
version	string	Schema version for migrations
project_id	string	Unique project identifier
project_name	string	Human-readable project name
next_id	number	Next assumption ID to assign
assumptions	array	Active assumptions
archived	array	Archived assumptions (future)

---

File Operations

Create New Ground File

1. Check if ~/.claude/common-ground/ exists, create if not
2. Create {project_id}/ directory
3. Write COMMON-GROUND.md from template
4. Write ground.index.json with empty assumptions
5. Update global index.md

Update Existing Ground File

1. Read ground.index.json
2. Apply changes (add/promote/demote)
3. Update last_updated timestamp
4. Regenerate COMMON-GROUND.md from index.json
5. Update global index.md counts

Read Ground File

1. Check if {project_id}/ground.index.json exists
2. If exists, parse JSON and return
3. If not exists, return null (trigger fresh start)

---

Writing Best Practices

Human-Readable (COMMON-GROUND.md)

• Use consistent markdown formatting
• Include horizontal rules between tiers
• Keep assumptions readable without JSON
• Include history table for audit trail

Machine-Readable (ground.index.json)

• Always valid JSON
• Include all fields (no omissions)
• Use ISO 8601 timestamps
• Preserve history array for audit

Sync Rules

• ground.index.json is source of truth
• COMMON-GROUND.md is generated from index.json
• Always update both on any change
• Never manually edit COMMON-GROUND.md (regenerate instead)

---

Error Handling

Scenario	Action
No home directory access	Warn user, suggest alternate path
Corrupted index.json	Backup and regenerate from COMMON-GROUND.md
Missing project directory	Create fresh on next run
Permission denied	Report error with path