Commit 154bba0

@@ -0,0 +1,129 @@
+# DEVELOPERS.md
+
+This file provides guidance to developers when working with code in this repository.
+
+## Project Overview
+
+Tissue (Terminal Issues) is a Go-based CLI tool for managing issue tracking directly within a Git repository using Markdown files with YAML front matter. Issues are stored in a dedicated `issues` branch managed via Git worktree, providing distributed issue tracking alongside the code.
+
+## Architecture
+
+The project follows a standard Go CLI application structure using the Cobra framework:
+
+- **main.go**: Entry point that calls the cmd package
+- **cmd/**: Contains all CLI command implementations
+  - `root.go`: Root command setup and command registration
+  - `init.go`: Implementation of the `tissue init` command for repository initialization
+- **issues/**: Git worktree directory for the issues branch (created after `tissue init`)
+- **docs/**: Documentation using mdBook
+
+Key Dependencies:
+- `github.com/spf13/cobra`: CLI framework for command structure
+- `github.com/go-git/go-git/v5`: Git operations library for repository manipulation
+- `github.com/go-git/go-billy/v5`: Filesystem abstraction for Git operations
+
+## Development Commands
+
+### Building
+```bash
+# Build with specific output
+go build -o bin/tissue
+```
+
+### Running
+```bash
+./bin/tissue [command]
+```
+
+### Testing
+```bash
+# Run all tests (when tests are added)
+go test ./...
+
+# Run tests with coverage
+go test -cover ./...
+
+# Run tests with verbose output
+go test -v ./...
+```
+
+### Dependencies
+```bash
+# Download dependencies
+go mod download
+
+# Tidy dependencies (remove unused, add missing)
+go mod tidy
+
+# Verify dependencies
+go mod verify
+```
+
+### Documentation
+```bash
+# Serve documentation locally (requires mdbook)
+mdbook serve docs
+
+# Build documentation
+mdbook build docs
+```
+
+## Code Patterns
+
+### Command Structure
+All commands follow the Cobra pattern:
+1. Create command function in `cmd/` (e.g., `NewInitCmd()`)
+2. Define flags in the command creation
+3. Implement RunE function for command execution
+4. Register command in `root.go` using `cmd.AddCommand()`
+
+### Error Handling
+- Always wrap errors with context using `fmt.Errorf("context: %w", err)`
+- Return errors from RunE functions - Cobra handles exit codes
+- Use early returns for error conditions
+
+### Git Operations
+- Use `go-git` library for Git operations
+- Open repository with `git.PlainOpen(".")`
+- Handle worktrees for the issues branch
+- Create orphan branches for issue storage
+
+## Issue File Structure
+
+Each issue is a Markdown file in the issues branch with YAML front matter:
+```yaml
+---
+title: Issue title
+status: open|closed|in-progress
+priority: low|medium|high|critical
+tags: [bug, feature, enhancement]
+assignee: username
+created: 2024-09-24T10:00:00Z
+updated: 2024-09-24T10:00:00Z
+---
+
+Issue description in Markdown...
+
+### Log
+- 2024-09-24 10:00: Created issue
+- 2024-09-24 11:00: Added comment
+```
+
+## Implementation Status
+
+Currently implemented:
+- Basic CLI structure with Cobra
+- `tissue init` command for repository initialization
+  - Creates orphan issues branch
+  - Sets up Git worktree in issues directory
+  - Creates initial README.md in issues branch
+
+Planned commands (from README):
+- `tissue new`: Create new issues
+- `tissue list/ls`: List and filter issues
+- `tissue search/grep`: Search issues
+- `tissue update/close/reopen`: Modify issue status
+- `tissue comment`: Add timestamped comments
+- `tissue index`: Generate issue summaries
+- `tissue import/export`: Import/export issues
+- `tissue config`: Configuration management