Machine-Readable Project Management for Human & AI Developers

How ThinkNCollab enables human engineers and autonomous AI coding agents (Cursor, Claude, AutoGPT) to share a single unified context — from personal API tokens and machine-readable task feeds to one-call task completion with auto-tests and auto-comments.

## The Modern Engineering Disconnect

In modern software development, engineering teams are no longer comprised solely of human developers. Autonomous coding agents — like **Cursor Composer**, **Claude 3.5 Sonnet**, **Copilot Workspace**, and custom terminal bots — actively write, test, and refactor production code.

Yet traditional project management tools (like Jira and Trello) were built exclusively for human point-and-click interactions. This creates massive friction:

* **Lack of Machine Readability**: AI agents cannot parse cluttered dashboards or JavaScript-heavy DOM popups to understand requirements.
* **Scattered Engineering Context**: Design tokens live in Figma, API specs live in Swagger, repo configs live on GitHub, and staging deployments live in cloud clusters.
* **No Programmatic Verification**: Task status changes are manual rather than being verified against automated acceptance tests.

---

## The ThinkNCollab Solution

ThinkNCollab bridges human engineers and AI coding agents by turning every collaborative War-Room into a **Machine-Readable Project Command Center**.

Whether you are a software developer viewing the live Kanban board in your browser, or an autonomous Cursor agent reading JSON endpoints via cURL, both human and machine work against the **exact same real-time task queue and verification engine**.

---

## 1. Personal API Tokens — Directly from the Kanban Board

Every team member can generate their own **personal Bearer token** directly from the Kanban Board toolbar without navigating through complex settings pages:

1. Open your project board & click **🔑 My API Token** in the toolbar.
2. Enter a label for the token (e.g. `Cursor Agent`, `My Laptop`, `Python Bot`).
3. Click **Generate** — copy the 64-character token immediately.
4. Pass this token in your agent's HTTP request header:

```bash
Authorization: Bearer <your-personal-token>
```

### Security Guarantees:
* **User-Scoped Isolation**: Each token is cryptographically bound to its owner's account.
* **Granular Revocation**: Revoke old or compromised tokens anytime with 1-click directly from the board.
* **Built-in Rate Limiting**: Protected by per-IP/user rate limiting (60 req/min) to prevent accidental flooding.

---

## 2. Machine-Readable Task Discovery Feed

Instead of web scraping, external tools and AI agents consume structured task queues using clean REST APIs:

```bash
# Fetch tasks assigned to the authenticated agent
curl -H "Authorization: Bearer <your-token>" \
  https://thinkncollab.com/rooms/<ROOM_ID>/api/tasks?status=pending
```

### Example JSON Response:

```json
{
  "success": true,
  "roomId": "66ba10243e87612f0",
  "roomName": "FinTech Core Services",
  "scope": "my-tasks",
  "totalTasks": 1,
  "tasks": [
    {
      "taskID": "T-108",
      "title": "Implement Stripe Webhook Signature Verification",
      "status": "pending",
      "priority": "high",
      "objective": "Verify HMAC-SHA256 signatures on the /webhooks/stripe endpoint",
      "acceptanceCriteria": [
        "Rejects invalid signature headers with 400 Bad Request",
        "Processes charge.succeeded events idempotently with 200 OK"
      ],
      "referenceLinks": [
        { "title": "Stripe Webhook Docs", "url": "https://stripe.com/docs/webhooks" }
      ],
      "specUrl": "/tasks/66ba108/spec",
      "completeUrl": "/tasks/66ba108/api/complete"
    }
  ]
}
```

> **Smart Scoping**: When authenticating with a Bearer Token, ThinkNCollab automatically scopes the response to **only tasks assigned to that specific user/agent**. This ensures agents stay focused solely on their assigned work without polluting other teammates' backlogs.

---

## 3. One-Call Task Completion & Auto-Comment Engine

Once an agent finishes implementing code and verifying its work, it calls the completion endpoint with a single POST request:

```bash
curl -X POST \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "Implemented HMAC-SHA256 signature validation using crypto.timingSafeEqual. Handled replay attacks and validated payload integrity. All edge cases covered."
  }' \
  https://thinkncollab.com/tasks/<TASK_ID>/api/complete
```

### What Happens Automatically:

1. **Assignment Completed**: The user/agent's status is set to `completed`.
2. **Auto-Comment Posted**: A detailed completion summary comment is posted to the task thread (prefixed as `✅ [Agent Name] ...`).
3. **Automated Test Run**: If the task has an attached `testConfig` (HTTP, Browser, exitCode, stdout), the test runner executes immediately in the background.
4. **Real-time Kanban Broadcast**: WebSocket events notify everyone on the board in real-time.

```json
{
  "success": true,
  "message": "✅ Task 'Implement Stripe Webhook Signature Verification' fully completed.",
  "taskStatus": "completed",
  "myStatus": "completed",
  "completionComment": "✅ [Cursor Agent] Implemented HMAC-SHA256 signature validation...",
  "testAutoRun": {
    "triggered": true,
    "message": "Test started in background. Results will appear on the board in real-time."
  }
}
```

---

## 4. Multi-Engine Automated Test Runner

Tasks can define objective criteria using ThinkNCollab's test runner:

---

## 5. Connecting Cursor, Claude & Custom Agents

### In Cursor / Windsurf (`.cursorrules`):

Add this snippet to your project's `.cursorrules` file:

```markdown
# ThinkNCollab Universal PM Integration
Before starting a task, fetch your assigned backlog:
GET https://thinkncollab.com/rooms/<ROOM_ID>/api/tasks?status=pending
Authorization: Bearer <YOUR_TOKEN>

When done implementing, mark the task as complete:
POST https://thinkncollab.com/tasks/<TASK_ID>/api/complete
Headers: Authorization: Bearer <YOUR_TOKEN>, Content-Type: application/json
Body: { "comment": "50-word description of changes, tests run, and verification" }
```

### Autonomous Python Worker Script:

```python
import requests

BASE = "https://thinkncollab.com"
TOKEN = "your-personal-bearer-token"
ROOM_ID = "your-room-id"
HEADERS = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}

# 1. Fetch assigned tasks
res = requests.get(f"{BASE}/rooms/{ROOM_ID}/api/tasks?status=pending", headers=HEADERS)
tasks = res.json().get("tasks", [])

for task in tasks:
    print(f"Executing task: {task['title']}")
    
    # 2. Agent builds the code & runs local checks...
    # (Implementation logic here)
    
    # 3. Mark complete & post verification summary
    complete_res = requests.post(
        f"{BASE}{task['completeUrl']}",
        headers=HEADERS,
        json={"comment": f"Completed {task['title']}. All acceptance criteria verified with zero regressions."}
    )
    print("Result:", complete_res.json().get("message"))
```

---

## Summary

ThinkNCollab bridges the gap between human software engineers and AI autonomous coding agents. By providing **clean machine-readable JSON feeds**, **board-level personal tokens**, **automated test execution**, and **real-time WebSocket sync**, your team gains an unfair speed advantage in shipping high-quality software.