Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 3 additions & 34 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,25 +16,23 @@

- Do not duplicate existing GitHub issues.
- Keep issue descriptions current when scope or reproduction steps change.
- Store AI-generated planning documents in `history/`, not the repository root;
the persistent root `IMPLEMENTATION.md` tracker described below is the exception.
- Store AI-generated planning documents in `history/`, not the repository root.
- **ALWAYS run `coderabbit --plain` before committing** to catch issues early.
- All commits must use the `taliesin-ai` identity.
- Never push until the user gives explicit manual confirmation.

### Managing AI-Generated Planning Documents

AI assistants often create planning and design documents during development:
- PLAN.md, IMPLEMENTATION.md, ARCHITECTURE.md
- PLAN.md, ARCHITECTURE.md
- DESIGN.md, CODEBASE_SUMMARY.md, INTEGRATION_PLAN.md
- TESTING_GUIDE.md, TECHNICAL_DESIGN.md, and similar files

**Best Practice: Use a dedicated directory for these ephemeral files**

**Recommended approach:**
- Create a `history/` directory in the project root
- Store all ephemeral AI-generated planning/design docs in `history/`;
keep the persistent root `IMPLEMENTATION.md` tracker in place
- Store all ephemeral AI-generated planning/design docs in `history/`
- Keep the repository root clean and focused on permanent project files
- Only access `history/` when explicitly asked to review past planning

Expand Down Expand Up @@ -87,35 +85,6 @@ measured bug they prevent.
implementation, follow `docs/src/content/docs/guides/streams-from-websockets.mdx` —
a mechanical checklist, including the differences that break silently.

## Implementation Tracking (IMPLEMENTATION.md)

**IMPORTANT**: The `IMPLEMENTATION.md` file at the repository root is a **persistent tracking document** for the GTK4 / WebKitGTK 6.0 / GTK3-legacy implementation work. It is NOT an ephemeral planning document.

As of 2026-05-16 (issue #5459), GTK4 + WebKitGTK 6.0 is the **default** Linux stack; GTK3 + WebKit2GTK 4.1 is a legacy opt-in (`-tags gtk3`) for one v3 cycle and is scheduled for removal in v3.1. The default-flip rationale is recorded in `IMPLEMENTATION.md` Decision 1.1.

### Requirements

1. **Update with EVERY commit** that touches GTK4/WebKitGTK 6.0 or legacy GTK3 code
2. **Track all architectural decisions** with context, decision, and rationale
3. **Maintain progress status** for each implementation phase
4. **Document API differences** between the GTK4 default and GTK3 legacy paths
5. **Keep file references** accurate and up-to-date

### What to Update

- Phase completion status (✅ COMPLETE, 🔄 IN PROGRESS, 📋 PENDING)
- New decisions made during implementation
- Files created or modified
- Changelog entries with dates
- TODO items discovered during work

### Commit Message Pattern

When updating IMPLEMENTATION.md:
```
docs: update implementation tracker for [phase/feature]
```

## Landing the Plane (Session Completion)

**When ending a work session**, complete the applicable steps below. Never push without explicit manual confirmation from the user.
Expand Down
Loading
Loading