From 4c5db3f95073bd86b67cf7120d5d4aba9cd7c3ce Mon Sep 17 00:00:00 2001 From: Tom Hicks Date: Sun, 23 Aug 2026 18:57:57 -0700 Subject: [PATCH] Adds agent rules. --- AGENTS.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ Tasks.md | 28 +++++++++++++++++++--------- 2 files changed, 69 insertions(+), 9 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..758fe40 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,50 @@ +# Agent Workflow & Project Guidelines + +This document defines the operating rules, task lifecycle, and development conventions for AI agents and contributors working in the **Nextcloud Upload Tool** repository. + +--- + +## 1. Core Operating Rules + +### Single-Task Execution +- **Strictly one task at a time**: Never bundle multiple tasks or implement features outside the currently assigned task. +- **Workflow Steps**: + 1. Inspect [Tasks.md](file:///Users/tom/Projects/Apps/NextcloudUploadTool/Tasks.md) to identify the next prioritized task. + 2. Transition the task status to `in_progress` in [Tasks.md](file:///Users/tom/Projects/Apps/NextcloudUploadTool/Tasks.md). + 3. Implement only the requirements specified in that task's checklist. + 4. Verify changes using the test and build suite (`cargo test --workspace` and frontend build in `gui`). + 5. Update [Tasks.md](file:///Users/tom/Projects/Apps/NextcloudUploadTool/Tasks.md) to mark the task `done` (Fixed), checking off completed requirements and updating the summary table. + 6. Pause and present results to the user for review and git commit. Do not proceed to the next task until the user acknowledges. + +### Git Operations +- **User-Managed Commits**: All `git commit`, branching, rebasing, resets, and destructive git commands are handled exclusively by the user. +- **Agent Git Scope**: + - Allowed: Read-only inspection (`git status`, `git diff`, `git log`) and staging (`git add`, `git rm`) if needed. + - Forbidden: Making commits, modifying files under `.git/`, or modifying git history. + +### Environment & Build Commands +- Node version: Node 20 as specified in [`.nvmrc`](file:///Users/tom/Projects/Apps/NextcloudUploadTool/.nvmrc). +- Backend tests: `cargo test --workspace` +- Frontend build: `cd gui && npm run build` + +--- + +## 2. Tasks.md Maintenance Rules + +### Single Source of Truth (SSOT) +- **Anchor Tags**: `` directly above each task heading is the SSOT for machine-readable attributes (`id`, `data-status`, `data-task-type`). +- **Task Details**: The markdown body under each heading is the SSOT for title, description, checklist items (`- [x]`), and direct dependencies. + +### Invariant Ordering +- **Tasks Summary Table**: + - Open/Active tasks (`triage`, `pending`, `in_progress`, `blocked`) are listed at the top. + - Completed (`done` / Fixed) tasks are listed at the bottom, sorted in **ascending numeric order** (`NUT-001`, `NUT-002`, ...). +- **Detailed Tasks Section**: + - All detailed task entries must remain in **strict monotonic numeric ascending order** (`NUT-001`, `NUT-002`, `NUT-003`, ...). + - Use two blank lines between detailed task blocks. + +--- + +## 3. Communication & Code Style +- Always use clickable GitHub-style file links (`[file.rs](file:///path/to/file.rs)`) and symbol links when referencing files or types in responses. +- Keep responses focused, concise, and aligned with the single task being executed. diff --git a/Tasks.md b/Tasks.md index cbf0b05..73f0564 100644 --- a/Tasks.md +++ b/Tasks.md @@ -60,7 +60,8 @@ This document defines the complete project roadmap and task tracking system for > - **Anchor Tags as SSOT**: The HTML anchor tag `` above each task heading is the single source of truth (SSOT) for ID, status, and task type. > - **Task Details as SSOT**: The detailed task body is the SSOT for title, description, requirements checklist, and direct dependencies. > - **Rendered Sections**: The [Tasks Summary](#tasks-summary) table and the bottom enum tables ([Task Statuses](#task-statuses) & [Task Types](#task-types)) are rendered views that must be synchronized whenever SSOT data changes. -> - **Full Documentation**: Review the complete rules, schemas, and contributor workflows in [Task System Documentation & Rules](#task-system-rules) before editing or restructuring tasks. +> - **Single Task Scope**: Implement only one task at a time, test and verify, update [Tasks.md](#tasks-summary), and pause for user commit. +> - **Full Documentation**: Review the complete rules, schemas, and contributor workflows in [Task System Documentation & Rules](#task-system-rules) and [AGENTS.md](file:///Users/tom/Projects/Apps/NextcloudUploadTool/AGENTS.md) before editing or restructuring tasks. --- @@ -326,12 +327,13 @@ Integrate rich progress reporting with `indicatif` (speed, ETA, byte counters), **Type:** Feature **Description:** -Implement the Tauri-based GUI application. +Implement the Tauri-based GUI application with a clean, responsive layout connecting the React frontend to the shared Rust backend. **Requirements:** -- [ ] Create window layout -- [ ] Connect Rust backend -- [ ] Implement basic upload UI +- [ ] Connect shared Rust backend library to Tauri commands in `gui/src-tauri` +- [ ] Implement responsive application layout with navigation & account indicator +- [ ] Implement file upload UI with destination path, public share link generation, and password protection +- [ ] Implement real-time feedback with share links, direct download URLs, and copy actions **Dependencies:** - NUT-002 @@ -626,11 +628,19 @@ Tasks progress through defined statuses: - Checklists must use standard GitHub Markdown `- [ ]` and `- [x]`. - Spacing: Use two blank lines between detailed task blocks. Horizontal rules (`---`) are reserved for separating major top-level sections. -### Maintenance Procedures +### Table & Section Sorting Rules -- **Adding a Task**: Append the next sequential ID, create the anchor tag and detailed section separated by two blank lines, and add the row to [Tasks Summary](#tasks-summary). -- **Updating Status/Type**: Update the `data-status` and `data-task-type` attributes in the task anchor tag, the text fields in the task detail section, and the corresponding row in [Tasks Summary](#tasks-summary). -- **Modifying Enums**: Any changes to available statuses or types must originate in the YAML frontmatter (`task-statuses` / `task-types`) and be re-rendered into the corresponding reference tables below. +- **Tasks Summary Table**: + - Non-fixed/open tasks (`triage`, `pending`, `in_progress`, `blocked`) are positioned at the top. + - Fixed/done tasks are positioned at the bottom, sorted in **ascending numeric order** by task ID (`NUT-001`, `NUT-002`, `NUT-003`, ...). +- **Detailed Tasks Section**: + - All detailed task sections remain in **strictly ascending numeric order** (`NUT-001`, `NUT-002`, `NUT-003`, ...). + +### Contributor & Agent Workflow + +1. **One Task at a Time**: Only one task is moved to `in_progress` and worked on per development turn. +2. **Verification First**: All unit and workspace tests (`cargo test --workspace`) and frontend builds (`cd gui && npm run build`) must pass cleanly before marking a task Fixed. +3. **Commit Handoff**: The agent updates [Tasks.md](#tasks-summary) upon task completion and pauses for the user to make the git commit. The agent does not execute commits or destructive git operations. ---