/file-management

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 | | C