Skip to content

Commit 0f8a908

Browse files
retr0hclaude
retr0h
and
claude
committed
docs: add CLAUDE.md, AGENTS.md, and development docs
Add AI agent guidance (AGENTS.md) with project overview, architecture quick reference, code standards, branching, and commit conventions. CLAUDE.md references AGENTS.md with Claude Code-specific additions. Add development.md and architecture.md to Docusaurus docs. Create .tasks/ directory with backlog items for bun migration and go-git replacement. Update contributing.md to cross-reference development.md. Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 61515ca commit 0f8a908

File tree

8 files changed

+543
-0
lines changed

8 files changed

+543
-0
lines changed

‎.tasks/README.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Task Tracking
2+
3+
Work is tracked as markdown files organized by status.
4+
5+
## Directory Structure
6+
7+
```
8+
.tasks/
9+
├── backlog/ # Tasks not yet started
10+
├── in-progress/ # Tasks actively being worked on
11+
├── done/ # Completed tasks
12+
└── sessions/ # Session work logs (what was done per Claude Code session)
13+
```
14+
15+
## Task File Format
16+
17+
Filename: `YYYY-MM-DD-short-description.md`
18+
19+
```markdown
20+
---
21+
title: Short description of the task
22+
status: backlog | in-progress | done
23+
created: YYYY-MM-DD
24+
updated: YYYY-MM-DD
25+
---
26+
27+
## Objective
28+
29+
What needs to be done and why.
30+
31+
## Notes
32+
33+
Decisions, context, blockers, or references.
34+
35+
## Outcome
36+
37+
What was accomplished (filled in when done).
38+
```
39+
40+
## Session Log Format
41+
42+
Filename: `YYYY-MM-DD.md`
43+
44+
```markdown
45+
---
46+
date: YYYY-MM-DD
47+
---
48+
49+
## Summary
50+
51+
Brief overview of what was accomplished.
52+
53+
## Changes
54+
55+
- List of files changed and why.
56+
57+
## Decisions
58+
59+
- Any architectural or design decisions made.
60+
61+
## Next Steps
62+
63+
- What to pick up next session.
64+
```
65+
66+
## Workflow
67+
68+
1. New work goes in `backlog/`
69+
2. Move file to `in-progress/` when starting
70+
3. Move file to `done/` when complete
71+
4. Log each Claude Code session in `sessions/`

‎.tasks/backlog/2026-02-16-replace-git-cli-with-go-git.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
title: Replace git CLI dependency with go-git
3+
status: backlog
4+
created: 2026-02-16
5+
updated: 2026-02-16
6+
---
7+
8+
## Objective
9+
10+
Remove the implicit runtime dependency on the git CLI by replacing it with
11+
[go-git](https://github.com/go-git/go-git). This would eliminate the
12+
requirement for git >= 2.20 to be installed and in `$PATH`, making Gilt fully
13+
self-contained.
14+
15+
go-git supports bare clones and has enough worktree support for what Gilt needs
16+
(clone, checkout specific version, copy files out).
17+
18+
## Blockers
19+
20+
- **Blocked on go-git partial clone support:**
21+
[go-git/go-git#1381](https://github.com/go-git/go-git/issues/1381).
22+
Gilt uses `--filter=blob:none` for efficient partial clones; go-git does not
23+
yet support this.
24+
25+
## Notes
26+
27+
- Related issue: [retr0h/gilt#72](https://github.com/retr0h/gilt/issues/72)
28+
- The current git CLI wrapper lives in `internal/git/` and implements the
29+
`GitManager` interface. The interface-based design means go-git can be
30+
swapped in as an alternative implementation with minimal changes to the
31+
rest of the codebase.
32+
- Consider a phased approach: implement go-git backend behind a flag first,
33+
fall back to CLI for partial clone operations until go-git catches up.
34+
35+
## Outcome
36+
37+
_To be filled in when complete._

‎.tasks/backlog/2026-02-16-switch-to-bun.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
title: Switch docs site package manager to bun
3+
status: backlog
4+
created: 2026-02-16
5+
updated: 2026-02-16
6+
---
7+
8+
## Objective
9+
10+
Replace yarn/npm with bun as the package manager for the Docusaurus
11+
documentation site.
12+
13+
## Notes
14+
15+
- `.mise.toml` already includes `bun = "latest"` so the runtime is available.
16+
- Requires updating `Taskfile.yml` docs tasks (currently reference yarn).
17+
- Update `package.json` scripts if needed.
18+
- Update CI workflows to use bun instead of yarn/npm.
19+
- Update `docs/docs/contributing.md` references to yarn.
20+
21+
## Outcome
22+
23+
_To be filled in when complete._

‎AGENTS.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# AGENTS.md
2+
3+
This file provides guidance to AI coding agents when working with code in this
4+
repository.
5+
6+
## Project Overview
7+
8+
Gilt is a Git repository overlay tool written in Go 1.25. It clones Git
9+
repositories, checks out specific versions (tags or SHAs), and copies files or
10+
directories into a target project. Module path: `github.com/retr0h/gilt/v2`.
11+
12+
## Development Reference
13+
14+
For setup, building, testing, and contributing, see the Docusaurus docs:
15+
16+
- @docs/docs/development.md - Prerequisites, setup, code style, testing, commit
17+
conventions
18+
- @docs/docs/contributing.md - PR workflow and contribution guidelines
19+
- @docs/docs/testing.md - How to run tests and list task recipes
20+
- @docs/docs/architecture.md - Package architecture and design patterns
21+
22+
Quick reference for common commands:
23+
24+
```bash
25+
task deps # Install all dependencies
26+
task test # Run all tests (lint + unit + coverage + bats)
27+
task unit # Run unit tests only
28+
task vet # Run golangci-lint
29+
task fmt # Auto-format (gofumpt + golines)
30+
task fmt:check # Check formatting without modifying
31+
go test -run TestName -v ./internal/... # Run a single test
32+
```
33+
34+
## Architecture (Quick Reference)
35+
36+
- **`cmd/`** - Cobra CLI commands (`root`, `overlay`, `init`, `version`)
37+
- **`internal/`** - Interface definitions (`git.go`, `exec.go`, `repository.go`,
38+
`repositories.go`)
39+
- **`internal/git/`** - Git CLI wrapper (clone, worktree, update, remote)
40+
- **`internal/exec/`** - Command execution abstraction
41+
- **`internal/repository/`** - Single repository operations (clone, worktree,
42+
copy sources)
43+
- **`internal/repositories/`** - Orchestrates overlay across all configured
44+
repositories
45+
- **`internal/path/`** - Path utility functions
46+
- **`internal/mocks/`** - Generated mocks (mockgen)
47+
- **`pkg/config/`** - Configuration types (`Repositories`, `Repository`,
48+
`Source`, `Command`) with Viper + validator tags
49+
- **`pkg/repositories/`** - Public API entry point for repository operations
50+
- **`test/integration/`** - Bats integration tests
51+
- **`docs/`** - Docusaurus documentation site
52+
- **`python/`** - Python wheel packaging for PyPI distribution
53+
54+
## Code Standards (MANDATORY)
55+
56+
### Testing
57+
58+
- Unit tests: `*_test.go` in same package for private functions
59+
- Public tests: `*_public_test.go` in test package (e.g., `package git_test`)
60+
for exported functions
61+
- Integration tests in `test/integration/` using Bats
62+
- Use `testify/assert` and `testify/require`
63+
64+
### Go Patterns
65+
66+
- Interface segregation: small interfaces in `internal/*.go`, implementations
67+
in sub-packages
68+
- Dependency injection via constructors (e.g., `NewGit(execManager)`)
69+
- Error wrapping: `fmt.Errorf("context: %w", err)`
70+
- Early returns over nested if-else
71+
- Unused parameters: rename to `_`
72+
- Import order: stdlib, third-party, local (blank-line separated)
73+
74+
### Linting
75+
76+
golangci-lint with: errcheck, errname, goimports, govet, prealloc, predeclared,
77+
revive, staticcheck. Formatting via gofumpt + golines.
78+
79+
### Branching
80+
81+
See @docs/docs/development.md#branching for full conventions.
82+
83+
When committing changes, create a feature branch first if currently on `main`.
84+
Branch names use the pattern `type/short-description` (e.g.,
85+
`feat/add-dns-retry`, `fix/memory-leak`, `docs/update-readme`).
86+
87+
### Commit Messages
88+
89+
See @docs/docs/development.md#commit-messages for full conventions.
90+
91+
Follow [Conventional Commits](https://www.conventionalcommits.org/) with the
92+
50/72 rule. Format: `type(scope): description`.
93+
94+
## Task Tracking
95+
96+
Work is tracked as markdown files in `.tasks/`. See @.tasks/README.md for
97+
format details.
98+
99+
```
100+
.tasks/
101+
├── backlog/ # Tasks not yet started
102+
├── in-progress/ # Tasks actively being worked on
103+
├── done/ # Completed tasks
104+
└── sessions/ # Session work logs (per session)
105+
```
106+
107+
When starting a session:
108+
109+
1. Check `.tasks/in-progress/` for ongoing work
110+
2. Check `.tasks/backlog/` for next tasks
111+
3. Move task files between directories as status changes
112+
4. Log session work in `.tasks/sessions/YYYY-MM-DD.md`

‎CLAUDE.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with
4+
code in this repository.
5+
6+
@AGENTS.md
7+
8+
When committing via Claude Code, end commit messages with:
9+
10+
- `Co-Authored-By: Claude <noreply@anthropic.com>`
11+
12+
### Claude Code Plugin
13+
14+
Install the **commit-commands** plugin for `/commit` and `/commit-push-pr`
15+
slash commands:
16+
17+
```
18+
/plugin install commit-commands@claude-plugins-official
19+
```

0 commit comments

Comments
 (0)