@mytechtoday/augment-extensions 0.1.0

package/modules/workflows/beads/rules/file-format.md

@@ -0,0 +1,283 @@
+# Beads File Format Specification
+
+## Overview
+
+Beads stores issues in `.beads/issues.jsonl` using JSONL (JSON Lines) format. Each line is a complete JSON object representing an issue or update.
+
+## JSONL Format
+
+**JSONL** = One JSON object per line, newline-separated.
+
+```jsonl
+{"id":"bd-a1b2","title":"Task 1","status":"open"}
+{"id":"bd-b2c3","title":"Task 2","status":"closed"}
+{"id":"bd-c3d4","title":"Task 3","status":"open"}
+```
+
+## Issue Schema
+
+### Minimal Issue
+
+```json
+{
+  "id": "bd-a1b2",
+  "title": "Implement user authentication",
+  "status": "open",
+  "created": "2024-01-20T10:00:00Z",
+  "updated": "2024-01-20T10:00:00Z"
+}
+```
+
+### Complete Issue
+
+```json
+{
+  "id": "bd-a1b2",
+  "title": "Implement user authentication",
+  "description": "Add JWT-based authentication with email/password login",
+  "status": "open",
+  "priority": 0,
+  "labels": ["backend", "auth", "security"],
+  "assignee": "agent-1",
+  "blocks": ["bd-b2c3", "bd-c3d4"],
+  "blocked_by": [],
+  "related": ["bd-d4e5"],
+  "parent": null,
+  "comments": [
+    {
+      "text": "Started implementation",
+      "author": "agent-1",
+      "timestamp": "2024-01-20T11:00:00Z"
+    }
+  ],
+  "created": "2024-01-20T10:00:00Z",
+  "updated": "2024-01-20T11:00:00Z",
+  "closed": null
+}
+```
+
+## Field Definitions
+
+### Required Fields
+
+- **id** (string): Unique hash-based ID, format: `bd-<hash>` or `bd-<hash>.<number>` for hierarchical
+- **title** (string): Short description of the task
+- **status** (string): One of: `"open"`, `"in-progress"`, `"blocked"`, `"closed"`
+- **created** (string): ISO 8601 timestamp
+- **updated** (string): ISO 8601 timestamp
+
+### Optional Fields
+
+- **description** (string): Detailed description
+- **priority** (integer): 0 (highest) to 3 (lowest), default: 2
+- **labels** (array of strings): Tags for categorization
+- **assignee** (string): Who is working on this
+- **blocks** (array of strings): IDs of tasks this task blocks
+- **blocked_by** (array of strings): IDs of tasks blocking this task
+- **related** (array of strings): IDs of related tasks
+- **parent** (string): ID of parent task (for hierarchical IDs)
+- **comments** (array of objects): Comments and updates
+- **closed** (string): ISO 8601 timestamp when closed
+
+## ID Format
+
+### Standard IDs
+
+Hash-based, 4-character hex:
+
+```
+bd-a1b2
+bd-b2c3
+bd-c3d4
+```
+
+### Hierarchical IDs
+
+Epic/task/subtask structure:
+
+```
+bd-a3f8        # Epic
+bd-a3f8.1      # Task under epic
+bd-a3f8.1.1    # Subtask
+bd-a3f8.2      # Another task under epic
+```
+
+## Status Values
+
+- **open** - Task is ready to work on (no blockers)
+- **in-progress** - Currently being worked on
+- **blocked** - Waiting on dependencies
+- **closed** - Completed or cancelled
+
+## Priority Values
+
+- **0** - Critical (P0)
+- **1** - High (P1)
+- **2** - Medium (P2) - default
+- **3** - Low (P3)
+
+## Dependency Types
+
+### blocks
+
+Tasks that this task prevents from starting:
+
+```json
+{
+  "id": "bd-a1b2",
+  "title": "Add database schema",
+  "blocks": ["bd-b2c3", "bd-c3d4"]
+}
+```
+
+Means: `bd-b2c3` and `bd-c3d4` cannot start until `bd-a1b2` is closed.
+
+### blocked_by
+
+Tasks that must be completed before this task can start:
+
+```json
+{
+  "id": "bd-b2c3",
+  "title": "Add API endpoint",
+  "blocked_by": ["bd-a1b2"]
+}
+```
+
+Means: `bd-b2c3` cannot start until `bd-a1b2` is closed.
+
+### related
+
+Tasks that are related but not blocking:
+
+```json
+{
+  "id": "bd-c3d4",
+  "title": "Add frontend form",
+  "related": ["bd-b2c3"]
+}
+```
+
+## Comments Format
+
+```json
+{
+  "comments": [
+    {
+      "text": "Started implementation",
+      "author": "agent-1",
+      "timestamp": "2024-01-20T11:00:00Z"
+    },
+    {
+      "text": "Added login endpoint",
+      "author": "agent-1",
+      "timestamp": "2024-01-20T12:00:00Z"
+    }
+  ]
+}
+```
+
+## Append-Only Log
+
+`.beads/issues.jsonl` is an **append-only log**. Updates are appended as new lines:
+
+```jsonl
+{"id":"bd-a1b2","title":"Task 1","status":"open","created":"2024-01-20T10:00:00Z","updated":"2024-01-20T10:00:00Z"}
+{"id":"bd-a1b2","status":"in-progress","updated":"2024-01-20T11:00:00Z"}
+{"id":"bd-a1b2","status":"closed","closed":"2024-01-20T12:00:00Z","updated":"2024-01-20T12:00:00Z"}
+```
+
+The **latest entry** for each ID is the current state.
+
+## Reading Issues
+
+### With CLI
+
+The CLI maintains a SQLite cache (`.beads/cache.db`) for fast queries:
+
+```bash
+bd list        # Query cache
+bd ready       # Query cache
+bd show bd-a1b2  # Query cache
+```
+
+### Without CLI
+
+Parse `.beads/issues.jsonl` manually:
+
+1. Read all lines
+2. Parse each line as JSON
+3. Group by `id`
+4. Merge fields (latest wins)
+5. Return current state
+
+## Writing Issues
+
+### With CLI
+
+```bash
+bd create "Title" -p 0
+# Appends to issues.jsonl and updates cache
+```
+
+### Without CLI
+
+Append JSON line to `.beads/issues.jsonl`:
+
+```bash
+echo '{"id":"bd-a1b2","title":"New task","status":"open","created":"2024-01-20T10:00:00Z","updated":"2024-01-20T10:00:00Z"}' >> .beads/issues.jsonl
+```
+
+## Configuration File
+
+`.beads/config.json`:
+
+```json
+{
+  "version": "1.0",
+  "stealth": false,
+  "compact_threshold": 100,
+  "auto_sync": true
+}
+```
+
+## Best Practices
+
+1. **Always append**: Never edit existing lines
+2. **Include timestamps**: Use ISO 8601 format
+3. **Unique IDs**: Use hash-based IDs to avoid conflicts
+4. **Atomic updates**: One field change per line
+5. **Validate JSON**: Ensure each line is valid JSON
+
+## Example Workflow
+
+### Create Task
+
+```jsonl
+{"id":"bd-a1b2","title":"Add authentication","status":"open","priority":0,"created":"2024-01-20T10:00:00Z","updated":"2024-01-20T10:00:00Z"}
+```
+
+### Add Dependency
+
+```jsonl
+{"id":"bd-a1b2","blocks":["bd-b2c3"],"updated":"2024-01-20T10:05:00Z"}
+```
+
+### Start Work
+
+```jsonl
+{"id":"bd-a1b2","status":"in-progress","updated":"2024-01-20T11:00:00Z"}
+```
+
+### Add Comment
+
+```jsonl
+{"id":"bd-a1b2","comments":[{"text":"Added login endpoint","timestamp":"2024-01-20T12:00:00Z"}],"updated":"2024-01-20T12:00:00Z"}
+```
+
+### Close Task
+
+```jsonl
+{"id":"bd-a1b2","status":"closed","closed":"2024-01-20T13:00:00Z","updated":"2024-01-20T13:00:00Z"}
+```
+

package/modules/workflows/beads/rules/manual-setup.md

@@ -0,0 +1,315 @@
+# Beads Manual Setup (Without CLI)
+
+## Overview
+
+You can use Beads without installing the CLI by working directly with `.beads/issues.jsonl` files. This guide shows how to set up and use Beads manually.
+
+## Initial Setup
+
+### 1. Create Directory Structure
+
+```bash
+mkdir .beads
+touch .beads/issues.jsonl
+```
+
+### 2. Create Configuration File
+
+Create `.beads/config.json`:
+
+```json
+{
+  "version": "1.0",
+  "stealth": false,
+  "compact_threshold": 100,
+  "auto_sync": true
+}
+```
+
+### 3. Add to .gitignore
+
+Add to `.gitignore`:
+
+```
+.beads/cache.db
+.beads/cache.db-*
+```
+
+**Note**: Commit `.beads/issues.jsonl` and `.beads/config.json`, but not the cache.
+
+### 4. Create AGENTS.md Integration
+
+Add to your project's `AGENTS.md` (or create it):
+
+```markdown
+# Beads Task Tracking
+
+This project uses Beads for task tracking. Issues are stored in `.beads/issues.jsonl`.
+
+## File Format
+
+Each line in `.beads/issues.jsonl` is a JSON object representing an issue or update.
+
+### Creating Tasks
+
+Append a JSON line:
+
+```json
+{"id":"bd-<hash>","title":"Task title","status":"open","priority":0,"created":"<ISO-8601>","updated":"<ISO-8601>"}
+```
+
+### Updating Tasks
+
+Append a JSON line with the same ID and updated fields:
+
+```json
+{"id":"bd-<hash>","status":"in-progress","updated":"<ISO-8601>"}
+```
+
+### Closing Tasks
+
+Append a JSON line with status "closed":
+
+```json
+{"id":"bd-<hash>","status":"closed","closed":"<ISO-8601>","updated":"<ISO-8601>"}
+```
+
+## Task States
+
+- **open** - Ready to work on
+- **in-progress** - Currently being worked on
+- **blocked** - Waiting on dependencies
+- **closed** - Completed
+
+## Dependencies
+
+Use `blocks` and `blocked_by` fields:
+
+```json
+{"id":"bd-a1b2","blocks":["bd-b2c3"],"updated":"<ISO-8601>"}
+```
+
+## Finding Ready Tasks
+
+Tasks are ready when:
+- Status is "open"
+- `blocked_by` is empty or all blockers are closed
+
+## Workflow
+
+1. Create task by appending to `.beads/issues.jsonl`
+2. Add dependencies with `blocks`/`blocked_by` fields
+3. Find ready tasks (no open blockers)
+4. Update status to "in-progress"
+5. Add comments as needed
+6. Close task when complete
+```
+
+## Generating Hash-Based IDs
+
+### Simple Method
+
+Use the first 4 characters of a hash:
+
+```bash
+# Linux/macOS
+echo -n "$(date +%s%N)" | md5sum | cut -c1-4
+
+# Or use a random string
+echo -n "task-$(date +%s)" | md5sum | cut -c1-4
+```
+
+### In Code (Python)
+
+```python
+import hashlib
+import time
+
+def generate_id():
+    hash_input = f"task-{time.time()}"
+    hash_hex = hashlib.md5(hash_input.encode()).hexdigest()
+    return f"bd-{hash_hex[:4]}"
+
+print(generate_id())  # bd-a1b2
+```
+
+### In Code (JavaScript)
+
+```javascript
+const crypto = require('crypto');
+
+function generateId() {
+  const hashInput = `task-${Date.now()}`;
+  const hash = crypto.createHash('md5').update(hashInput).digest('hex');
+  return `bd-${hash.substring(0, 4)}`;
+}
+
+console.log(generateId());  // bd-a1b2
+```
+
+## Creating Your First Task
+
+### 1. Generate ID
+
+```bash
+# Generate a unique ID
+ID="bd-$(echo -n "task-$(date +%s)" | md5sum | cut -c1-4)"
+echo $ID  # bd-a1b2
+```
+
+### 2. Create JSON
+
+```bash
+# Create task JSON
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+TASK=$(cat <<EOF
+{"id":"$ID","title":"Implement user authentication","status":"open","priority":0,"created":"$TIMESTAMP","updated":"$TIMESTAMP"}
+EOF
+)
+```
+
+### 3. Append to File
+
+```bash
+echo "$TASK" >> .beads/issues.jsonl
+```
+
+## Working with AI Agents
+
+### Creating Tasks
+
+Ask your AI:
+
+```
+Create a Beads task for implementing user authentication with priority 0.
+Append the JSON to .beads/issues.jsonl with a unique hash-based ID.
+```
+
+The AI will:
+1. Generate a unique ID (e.g., `bd-a1b2`)
+2. Create JSON with required fields
+3. Append to `.beads/issues.jsonl`
+
+### Finding Ready Tasks
+
+Ask your AI:
+
+```
+What Beads tasks are ready to work on?
+Parse .beads/issues.jsonl and find tasks where:
+- status is "open"
+- blocked_by is empty or all blockers are closed
+```
+
+### Updating Tasks
+
+Ask your AI:
+
+```
+Update Beads task bd-a1b2 to status "in-progress"
+Append an update to .beads/issues.jsonl
+```
+
+### Adding Dependencies
+
+Ask your AI:
+
+```
+Make Beads task bd-b2c3 depend on bd-a1b2
+Append updates to .beads/issues.jsonl:
+- bd-a1b2 blocks bd-b2c3
+- bd-b2c3 is blocked_by bd-a1b2
+```
+
+## Reading Current State
+
+### Parse JSONL (Python)
+
+```python
+import json
+
+def read_issues(filepath='.beads/issues.jsonl'):
+    issues = {}
+    with open(filepath, 'r') as f:
+        for line in f:
+            issue = json.loads(line.strip())
+            issue_id = issue['id']
+            if issue_id not in issues:
+                issues[issue_id] = {}
+            issues[issue_id].update(issue)
+    return issues
+
+# Get all issues
+all_issues = read_issues()
+
+# Find ready tasks
+ready_tasks = [
+    issue for issue in all_issues.values()
+    if issue.get('status') == 'open' and not issue.get('blocked_by')
+]
+```
+
+### Parse JSONL (JavaScript)
+
+```javascript
+const fs = require('fs');
+
+function readIssues(filepath = '.beads/issues.jsonl') {
+  const issues = {};
+  const lines = fs.readFileSync(filepath, 'utf-8').split('\n');
+  
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    const issue = JSON.parse(line);
+    const issueId = issue.id;
+    if (!issues[issueId]) {
+      issues[issueId] = {};
+    }
+    Object.assign(issues[issueId], issue);
+  }
+  
+  return issues;
+}
+
+// Get all issues
+const allIssues = readIssues();
+
+// Find ready tasks
+const readyTasks = Object.values(allIssues).filter(
+  issue => issue.status === 'open' && (!issue.blocked_by || issue.blocked_by.length === 0)
+);
+```
+
+## Limitations Without CLI
+
+- ❌ No SQLite cache (slower queries)
+- ❌ No auto-sync daemon
+- ❌ No validation
+- ❌ No compaction
+- ❌ Manual ID generation
+- ❌ Manual JSONL parsing
+
+## Benefits Without CLI
+
+- ✅ No installation required
+- ✅ Works immediately
+- ✅ Full control over data
+- ✅ Simple git workflow
+- ✅ Compatible with all AI agents
+
+## Upgrading to CLI Later
+
+If you decide to install the CLI later:
+
+```bash
+npm install -g @beads/bd
+cd your-project
+bd init
+```
+
+The CLI will:
+- Detect existing `.beads/issues.jsonl`
+- Build SQLite cache from existing data
+- Start auto-sync daemon
+- Continue working with your existing issues
+