---
phase: 14-documentation
plan: 01
type: execute
wave: 1
depends_on: []
files_modified: [README.md]
autonomous: true

must_haves:
  truths:
    - "README displays badges for CI, PyPI version, and Python versions"
    - "User can find installation instructions within 10 seconds of opening README"
    - "User can understand what commands are supported via command matrix table"
    - "User can see flag support status for each command"
    - "User understands what happens with unsupported commands"
  artifacts:
    - path: "README.md"
      provides: "Complete documentation for gitsl"
      min_lines: 150
      contains:
        - "pip install gitsl"
        - "shields.io"
        - "Supported Commands"
        - "Unsupported Commands"
  key_links:
    - from: "README.md badges"
      to: "shields.io dynamic URLs"
      via: "img.shields.io links"
      pattern: "img\\.shields\\.io"
    - from: "command matrix"
      to: "actual supported commands"
      via: "table matching gitsl.py dispatch"
      pattern: "status.*log.*diff.*init.*add.*commit"
---

<objective>
Create production-quality README.md with badges, installation, usage examples, command matrix, and flag documentation.

Purpose: Complete Phase 14 requirements (DOC-01 through DOC-08) for v1.1 release
Output: README.md ready for PyPI and GitHub display
</objective>

<execution_context>
@~/.claude/get-shit-done/workflows/execute-plan.md
@~/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/phases/14-documentation/14-RESEARCH.md

# Source files for accurate command/flag documentation
@gitsl.py
@cmd_status.py
@cmd_log.py
@cmd_add.py
@cmd_rev_parse.py
@cmd_diff.py
@cmd_init.py
@cmd_commit.py
@pyproject.toml
</context>

<tasks>

<task type="auto">
  <name>Task 1: Create README structure with badges and installation</name>
  <files>README.md</files>
  <action>
Replace existing placeholder README.md with production documentation.

**Structure:**
1. Title: `# gitsl`
2. Badge row (horizontal, linked):
   - CI: `[![CI](https://img.shields.io/github/actions/workflow/status/owner/gitsl/ci.yml?branch=master)](https://github.com/owner/gitsl/actions)`
   - PyPI: `[![PyPI](https://img.shields.io/pypi/v/gitsl)](https://pypi.org/project/gitsl/)`
   - Python: `[![Python](https://img.shields.io/pypi/pyversions/gitsl)](https://pypi.org/project/gitsl/)`
3. One-line description: "Git to Sapling CLI shim - translates git commands to their Sapling (sl) equivalents."

**Installation section:**
```markdown
## Installation

```bash
pip install gitsl
```

Requires Python 3.8 or later. Requires [Sapling](https://sapling-scm.com/) to be installed and available as `sl`.
```

**Quick Start section (3-4 examples):**
```markdown
## Quick Start

Use familiar git commands in any Sapling repository:

```bash
# Check status (outputs git-compatible format)
gitsl status --porcelain

# View recent commits
gitsl log --oneline -5

# Stage and commit changes
gitsl add -A
gitsl commit -m "Your message"
```

gitsl translates these to equivalent Sapling commands automatically.
```

**Note:** Use `owner` as placeholder in badge URLs - will be updated when actual GitHub org is known.
  </action>
  <verify>README.md exists with badges, installation, and quick start sections</verify>
  <done>
    - Badge row with 3 shields.io links at top
    - Installation section with pip command and Python/Sapling requirements
    - Quick Start section with 4 example commands
  </done>
</task>

<task type="auto">
  <name>Task 2: Add command matrix and per-command flag documentation</name>
  <files>README.md</files>
  <action>
Append command reference sections to README.md after Quick Start.

**Supported Commands matrix (derived from gitsl.py dispatch):**
```markdown
## Supported Commands

| Command | Status | Translation |
|---------|--------|-------------|
| `init` | Full | `sl init` |
| `status` | Full | `sl status` with output transformation |
| `log` | Full | `sl log` with flag translation |
| `diff` | Full | `sl diff` |
| `add` | Full | `sl add` / `sl addremove` |
| `commit` | Full | `sl commit` |
| `rev-parse` | Partial | Only `--short HEAD` via `sl whereami` |

Commands not listed are unsupported.
```

**Per-command flag tables (derived from cmd_*.py files):**

### git status
| Flag | Supported | Behavior |
|------|-----------|----------|
| (none) | Yes | Passthrough to `sl status` |
| `--porcelain` | Yes | Output transformed to git XY format |
| `--short` / `-s` | Yes | Output transformed to git XY format |
| other flags | Partial | Passed through to sl |

Include status code translation table (M -> " M", A -> "A ", R -> "D ", ? -> "??", ! -> " D").

### git log
| Flag | Supported | Translation |
|------|-----------|-------------|
| (none) | Yes | `sl log` |
| `--oneline` | Yes | `sl log -T "{node|short} {desc|firstline}\n"` |
| `-N` (e.g., `-5`) | Yes | `sl log -l N` |
| `-n N` | Yes | `sl log -l N` |
| `--max-count=N` | Yes | `sl log -l N` |
| `--format` | No | Not implemented |
| `--graph` | No | Not implemented |

### git add
| Flag | Supported | Translation |
|------|-----------|-------------|
| `<files>` | Yes | `sl add <files>` |
| `-A` / `--all` | Yes | `sl addremove` |
| `-u` / `--update` | Yes | Marks deleted files with `sl remove --mark` |
| `-p` / `--patch` | No | Not implemented |

### git diff, git init, git commit
All flags passed through to sl equivalents.

### git rev-parse
| Flag | Supported | Translation |
|------|-----------|-------------|
| `--short HEAD` | Yes | `sl whereami` (truncated to 7 chars) |
| other variants | No | Returns error |
  </action>
  <verify>README.md contains command matrix table and per-command flag sections</verify>
  <done>
    - Command support matrix with all 7 commands
    - Flag tables for status, log, add, rev-parse
    - Passthrough note for diff, init, commit
    - Status code translation table
  </done>
</task>

<task type="auto">
  <name>Task 3: Add unsupported commands section and debug mode</name>
  <files>README.md</files>
  <action>
Append final sections to README.md.

**Unsupported Commands section (DOC-05):**
```markdown
## Unsupported Commands

Commands not listed above will print a message to stderr and exit with code 0:

```
gitsl: unsupported command: git checkout main
```

This exit behavior prevents gitsl from breaking tools that expect git commands to succeed.

For unsupported operations, use Sapling commands directly. See the [Sapling Git Cheat Sheet](https://sapling-scm.com/docs/introduction/git-cheat-sheet/) for translations.

### Why Some Commands Are Unsupported

| Command | Reason |
|---------|--------|
| `checkout` | Sapling uses `goto` with different semantics |
| `branch` | Sapling uses bookmarks, different model |
| `merge` | Sapling prefers rebase workflow |
| `rebase` | Complex flag translation, use `sl rebase` directly |
| `stash` | Use `sl shelve` / `sl unshelve` directly |
| `push` / `pull` / `fetch` | Remote operations differ significantly |
```

**Debug Mode section:**
```markdown
## Debug Mode

Set `GITSL_DEBUG=1` to see what command would be executed without running it:

```bash
$ GITSL_DEBUG=1 gitsl status --porcelain
[DEBUG] Command: status
[DEBUG] Args: ['--porcelain']
[DEBUG] Would execute: sl status
```
```

**How It Works section (brief):**
```markdown
## How It Works

gitsl intercepts git commands and translates them to Sapling equivalents:
1. Parses the git command and flags
2. Translates to corresponding sl command
3. Transforms output to git-compatible format where needed (status, log)
4. Returns sl's exit code

For commands without translation, gitsl prints a message to stderr and exits 0.
```

**License section:**
```markdown
## License

MIT
```
  </action>
  <verify>README.md contains unsupported commands table with reasons, debug mode section, and license</verify>
  <done>
    - Unsupported commands explanation with exit 0 behavior
    - Table with reasons for 6+ unsupported commands
    - Link to Sapling Git Cheat Sheet
    - Debug mode usage example
    - How it works overview
    - MIT license note
  </done>
</task>

</tasks>

<verification>
After all tasks complete:

1. README.md structure check:
   ```bash
   head -20 README.md  # Should show title, badges, description
   ```

2. Badge syntax validation:
   ```bash
   grep -c "img.shields.io" README.md  # Should be 3 (CI, PyPI, Python)
   ```

3. Required content present:
   ```bash
   grep -c "pip install gitsl" README.md  # Should be >= 1
   grep -c "Supported Commands" README.md  # Should be 1
   grep -c "Unsupported Commands" README.md  # Should be 1
   grep -c "GITSL_DEBUG" README.md  # Should be >= 1
   ```

4. Line count (should be ~150-250 lines for complete docs):
   ```bash
   wc -l README.md
   ```

5. Requirements coverage:
   - DOC-01: "pip install gitsl" present
   - DOC-02: Quick Start section with examples
   - DOC-03: Command support matrix table
   - DOC-04: Per-command flag tables
   - DOC-05: Unsupported commands with reasons
   - DOC-06: CI badge (shields.io github/actions)
   - DOC-07: PyPI badge (shields.io pypi/v)
   - DOC-08: Python badge (shields.io pypi/pyversions)
</verification>

<success_criteria>
Phase 14 complete when:
- [ ] README.md has 3 shields.io badges at top
- [ ] Installation section with pip command
- [ ] Quick Start with 4 example commands
- [ ] Command matrix table with all 7 commands
- [ ] Per-command flag tables for status, log, add, rev-parse
- [ ] Unsupported commands section with exit 0 explanation
- [ ] Reasons table for why commands are unsupported
- [ ] Debug mode section with GITSL_DEBUG example
- [ ] All DOC-01 through DOC-08 requirements addressed
</success_criteria>

<output>
After completion, create `.planning/phases/14-documentation/14-01-SUMMARY.md`
</output>
