myworkspace/.clinerules

# Global Steering Guidance for MyWorkspace
# =============================================================================
# This file contains global steering guidance that applies across all projects
# within the MyWorkspace folder. Cline should apply this guidance in addition
# to any project-specific rules found in subfolder .clinerules files.
# =============================================================================

# -----------------------------------------------------------------------------
# WORKSPACE STRUCTURE & LOCATION
# -----------------------------------------------------------------------------

- [x] Initialize all projects as git repositories
- [x] Verify git checkpoints work correctly before committing
- [x] Configure and push all projects to remote source at self-hosted gitea.blabber1565.com
- [x] Place ALL downloaded resources (including git repo clones) within MyWorkspace folder
- [x] Place ALL generated resources within MyWorkspace folder
- [x] Avoid placing files outside MyWorkspace to prevent access permissions issues

# -----------------------------------------------------------------------------
# DOCUMENTATION FILES (Required for every project)
# -----------------------------------------------------------------------------

### Workspace Level Files (Global)
- [ ] Use `TODOs.txt` at workspace level for global TODOs and cross-project items
- [ ] Use `README.md` at workspace level for workspace overview and project navigation
- [ ] Use `chatlog.md` at workspace level for cross-project communication logs
- [ ] Use `docs/` folder at workspace level for shared documentation

### Project Level Files (Project-Specific)
- [ ] Use `README.md` at project level for project overview and setup instructions
- [ ] Use `TODOs.txt` at project level for project-specific TODOs
- [ ] Use `chatlog.md` at project level for project-specific communication logs
- [ ] Use `design.md` at project level for architecture and design documentation
- [ ] Use `tasks.md` at project level for tracking implementation tasks

# -----------------------------------------------------------------------------
# CHAT LOGGING GUIDANCE (AUTOMATIC)
# -----------------------------------------------------------------------------

### Automatic Logging Behavior:
- [x] **Cline automatically saves chat sessions to chatlog.md files**
- [ ] Workspace-level chatlog.md: `n:\Data\Users\David\MyWorkspace\chatlog.md`
- [ ] Project-level chatlog.md: `n:\Data\Users\David\MyWorkspace\@projectname\chatlog.md`
- [ ] **Important: Use project name format in path** (e.g., `@linkdingsync\chatlog.md`)
- [ ] Chat logs should capture important decisions, context, and communication history
- [ ] Logs help maintain continuity when resuming work on projects
- [ ] Important context and decisions are preserved for future reference

### Chatlog Management Best Practices:
- **Do NOT manually edit chatlog.md** - Cline auto-saves these
- **Use project name format** in path: `@projectname\chatlog.md`
- **Review chatlogs** for post-action evaluation (what went well/what didn't)
- **Keep workspace chatlog** for cross-project communication and coordination
- **Consider using hooks** to copy important chat sessions to a central archive

### Chatlog Archiving Strategy:
- **Option A (Recommended):** Review chatlogs during checkpoint reviews manually
- **Option B:** Use a hook to copy chatlog content to `docs/session-YYYYMMDD.md` at task completion
- **Option C:** Configure workspace chatlog for all important decisions

### Why Chatlogs May Not Appear Updated:
- Cline saves chatlogs as separate files (not in IDE working set)
- Each chat session may append to file rather than replacing
- To review: Open the chatlog.md file directly from file explorer
- To archive: Copy chatlog content to docs/ folder manually or via hook

# -----------------------------------------------------------------------------
# CODE QUALITY & STANDARDS
# -----------------------------------------------------------------------------

### Testing
- [ ] Include testing during implementation (write tests alongside code)
- [ ] Run test execution before marking tasks as complete
- [ ] Ensure test coverage meets project requirements

### Code Comments
- [ ] Include comments for code-based documentation during code generation
- [ ] Add comments explaining non-obvious logic and complex algorithms
- [ ] Include docstrings for functions and classes

### Security & Maintainability
- [ ] Follow coding standards for security (input validation, secure coding patterns)
- [ ] Write maintainable, readable code with consistent formatting
- [ ] Use meaningful variable and function names
- [ ] Avoid hardcoding secrets; use environment variables or secure storage
- [ ] Follow language/framework-specific best practices

# -----------------------------------------------------------------------------
# MULTI-AGENT WORKFLOW GUIDANCE
# -----------------------------------------------------------------------------

## Agent Overview

| Agent | Role | Strengths | Typical Use Cases |
|-------|------|-----------|-------------------|
| **Cline** | Orchestrator/Planner | IDE integration, human-in-the-loop, approval workflow | Task scoping, product refinement, change review |
| **OpenCode** | Terminal Execution Specialist | Self-hosted, AGENTS.md support, local models | Test harness iteration, debugging loops, multi-file refactors |
| **Aider** | Quick CLI Assistant | Simple, fast, model-flexible | Small refactor tasks, one-off fixes |
| **Playwright** | E2E Testing Harness | Cross-browser automation, API interaction | Browser extension testing, E2E test coverage |
| **E2B** | Sandbox Runner | Safe code execution | Running generated test code, snippet validation |

## Agent Handoff Protocol

### When to Delegate to OpenCode/Aider
- Task requires multiple diagnosis-fix cycles
- Test harness needs iterative setup/execution/teardown
- Multi-file refactoring or repair
- Debugging repetitive failure loops
- Task exceeds Cline's iterative patience threshold

### When Cline Should Retain Control
- Product behavior refinement
- Architecture-level decisions
- User-facing feature implementation
- Final change approval and integration
- Cross-project coordination

### Handoff Trigger Checklist
- [ ] Task brief written in `<project-root>/task-brief.md`
- [ ] AGENTS.md updated with project context
- [ ] Acceptance criteria clearly defined
- [ ] Estimated time budget documented
- [ ] User approves handoff initiation

## Progress Monitoring & Re-think Triggers

### Time Estimates
- Initial estimate always documented in task brief
- Checkpoint reviews at 50% and 90% of estimated time
- Re-think threshold: **2x estimated time without progress**
- Re-think threshold: **3x estimated time with any blocker**

### Checkpoint Review Process
1. Verify agent is still making progress
2. Check for repeating patterns in failures
3. Identify any blockers or missing context
4. If re-think needed: pause agent, update AGENTS.md, resume

### Re-think Options
- Update AGENTS.md with new context
- Change tooling (e.g., switch from OpenCode to Aider)
- Adjust test strategy or approach
- Request user clarification on requirements
- Escalate to Cline for product-level decisions

## Tooling Stack

### Core Agents
```
┌─────────────────────────────────────────────────────┐
│ Primary: OpenCode                                     │
│   - Self-hosted (Ollama/your models)                  │
│   - AGENTS.md project memory                           │
│   - Terminal-first iteration                          │
└─────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────┐
│ Secondary: Aider                                      │
│   - Simple CLI interface                               │
│   - Good for smaller, focused tasks                    │
│   - Can be used alongside OpenCode                     │
└─────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────┐
│ Specialized: E2B                                     │
│   - Safe sandbox execution                             │
│   - Run generated test code                           │
│   - Validate test harness logic                        │
└─────────────────────────────────────────────────────┘
```

### Browser Automation
```
┌─────────────────────────────────────────────────────┐
│ Playwright                                           │
│   - Cross-browser E2E testing                         │
│   - API call automation                               │
│   - Network interception                              │
│   - Use in: OpenCode or Aider task context           │
└─────────────────────────────────────────────────────┘
```

### Installation Commands
```bash
# OpenCode (via Claude Code if needed)
npm install -g @anthropic-ai/claude-code

# Or download OpenCode CLI from:
# https://github.com/anomalyco/opencode

# Aider
pip install aider-chat

# Playwright (browser automation)
npm install -D @playwright/test
npx playwright install

# E2B (sandbox runner)
npm install @e2b/sdk
```

## AGENTS.md Template (Create in each project)

```markdown
# AGENTS.md - Project Guidance for Coding Agents

## Project Overview
[2-3 sentence description of what this project does]

## Setup & Build Commands
- **Build**: `npm run build` / `make build` / etc.
- **Test**: `npm test` / `pytest` / `make test`
- **Lint**: `npm run lint`
- **Dev**: `npm run dev`
- **Browser Tests**: `npx playwright test`

## Architecture Notes
[Brief description of key components and data flow]

## Testing Protocol
- Unit tests must pass before committing
- E2E tests: run via Playwright commands
- Test coverage target: [X]%
- Browser automation requirements: [specifics]

## Conventions
- **File naming**: [conventions]
- **Error handling**: [approach]
- **API patterns**: [patterns used]
- **Do not modify**: [protected files]

## Known Issues / Technical Debt
[List of known problems and their status]

## Project-Specific Tools
- Custom CLI tools: [commands]
- Local services: [what runs, how to start]
- API endpoints: [key endpoints]
```

## Cline Customization Mechanisms

### .clinerules (Global/Workspace)
- Always-on guidance for all projects
- Cross-project conventions and patterns
- Agent handoff policies
- Global tooling preferences

### Project-specific .clinerules
- Project-specific agent instructions
- Local tool configurations
- Project-specific conventions
- Override global rules where needed

### Workflows (Task Templates)
Step-by-step task definitions:
1. Define task steps in markdown
2. Assign specific agents to each step
3. Use for repeatable multi-step tasks

Example workflow file:
```markdown
# task-delegate-to-opencode.md

## Step 1
Gather acceptance criteria from user or task brief

## Step 2
Write or update AGENTS.md with project context

## Step 3
Create task brief in `<root>/task-brief.md`

## Step 4
Launch OpenCode with task brief
```bash
opencode --task task-brief.md
```

## Step 5
Review output and approve changes

## Step 6
Mark task as complete in tasks.md
```

### Hooks (Pre/Post Action)
Hooks run at known moments and can:
- Detect test-heavy/repetitive tasks
- Suggest OpenCode handoff automatically
- Validate operations before execution
- Inject latest AGENTS.md into context
- **Copy chatlog to archive on task completion** (recommended for post-review)

### Skills (Contextual Expertise)
Skills provide on-demand knowledge:
- Add Playwright expertise before browser tasks
- Inject API documentation before integration
- Load project architecture notes before major changes

### Hook vs Rule Decision Matrix
| Need | Use Hook | Use Rule |
|------|----------|----------|
| Always-on guidance | Rule | |
| Task-specific enforcement | Hook | |
| Automatic chatlog archiving | **Hook** (recommended) | |
| Time-based checkpoint alerts | **Hook** | |
| Global conventions | Rule | |

## Task Brief Template (task-brief.md)

```markdown
# Task Brief: [Title]

## Context
[Brief background on what led to this task]

## Goal
[What needs to be achieved]

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

## Constraints
- [ ] Constraint 1 (e.g., "Don't modify auth module")
- [ ] Constraint 2 (e.g., "Must use existing API pattern")

## Related Files
- [ ] File 1
- [ ] File 2

## Notes from Previous Iterations
[Any relevant info from earlier attempts]

## Chatlog Reference
- Session log: `@projectname/chatlog.md`
- Archived: `docs/session-YYYYMMDD.md` (if archived)
```

## Workflow Summary

```
┌─────────────────────────────────────────────────────────┐
│ 1. CLINE (IDE) - Task Initiation                         │
│    • Define task and acceptance criteria                  │
│    • Create/update task-brief.md                          │
│    • Update AGENTS.md with project context                │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│ 2. CLINE - Agent Launch                                  │
│    • Review .clinerules for guidance                      │
│    • Launch OpenCode/Aider with task brief                │
│    • Record time estimate and checkpoint plan             │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│ 3. OPENCODE/AIDER - Autonomous Iteration                 │
│    • Read AGENTS.md for project context                   │
│    • Execute task per task-brief.md                       │
│    • Run tests repeatedly until stable                    │
│    • Report on progress or blockers                       │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│ 4. CLINE - Checkpoint Review                             │
│    • Review progress at 50% and 90% of estimate           │
│    • Detect stuck loops or blockers                       │
│    • Decide: continue, re-think, or escalate              │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│ 5. CLINE - Integration & Approval                        │
│    • Review diff from agent work                          │
│    • Approve/reject changes                               │
│    • Add final product-level refinements                   │
│    • Copy chatlog to archive if needed                      │
│    • Commit and push to git                               │
└─────────────────────────────────────────────────────────┘
```

## Next Actions for This Session

1. **Install tooling** (in Act mode when ready)
   - OpenCode CLI
   - Aider
   - Playwright
   - E2B (optional)

2. **Update project documentation**
   - Create AGENTS.md in Linkding Browser Extension
   - Create task-brief.md for test harness task
   - Update .clinerules with new agent guidance

3. **Execute proof of concept**
   - Use agents to build test harness for LinkdingSync
   - Document what works and what doesn't
   - Refine workflow based on results

# -----------------------------------------------------------------------
# REMOTE SOURCE CONFIGURATION
# -----------------------------------------------------------------------------

### Git Repository Configuration:
- [x] Self-hosted git repository: gitea.blabber1565.com
- [x] Single local repo at `n:\Data\Users\David\MyWorkspace`
- [x] Single remote repo at `git@gitea.blabber1565.com:david/myworkspace`
- [x] Use HTTPS with personal access token for authentication
- [x] .netrc file configured for passwordless access

### Git Commands Reference:
```bash
# Initialize local repo
git init

# Add all files to tracking
git add .

# Commit changes
git commit -m "description"

# Configure remote
git remote add origin git@gitea.blabber1565.com:david/myworkspace
# OR with HTTPS token:
git remote set-url origin https://<TOKEN>@gitea.blabber1565.com/david/myworkspace.git

# Switch to main branch
git branch -M main

# Push to remote
git push -u origin main
```

# -----------------------------------------------------------------------------
# FILE ORGANIZATION CONVENTIONS
# -----------------------------------------------------------------------------

### Required files per project:
- README.md - Project overview
- TODOs.txt - Project TODOs
- design.md - Architecture/design documentation (recommended)
- tasks.md - Task tracking (recommended)
- AGENTS.md - Agent guidance (recommended)
- docs/ - Project documentation folder (recommended)
- task-brief.md - Current active task brief (when agent working)

### Workspace-level files:
- TODOs.txt - Global TODOs
- README.md - Workspace overview
- chatlog.md - `n:\Data\Users\David\MyWorkspace\chatlog.md` (global chat log)
- docs/ - Shared documentation
- .clinerules - Global steering guidance (this file)

### Testing:
- tests/ or test/ folder for test files
- playwright.config.ts (if using Playwright)
- pytest.ini or equivalent for test configuration (if applicable)

### Chatlog Management:
- Cline auto-saves to `@projectname/chatlog.md`
- Review during checkpoint reviews
- Archive important sessions to `docs/session-YYYYMMDD.md`
- Workspace chatlog for cross-project coordination

### NOTE: Workspace Checkpoints
- Git checkpoints are now supported (only MyWorkspace is configured as workspace root)
- Chat logs automatically save to appropriate chatlog.md files
- This configuration ensures Cline can track conversation state properly