Automation guide

AI-agent operating workflow

An agent should treat Twindem as shared delivery state, not as an optional reporting step at the end. Read before acting and update the sources of truth while the work progresses.

1. Bootstrap project context

GET /api/auth/context
GET /api/board/projects/<projectId>
GET /api/board/projects/<projectId>/work-items?phase=in_progress&limit=50
GET /api/docs/projects/<projectId>/pages
GET /api/swagger/projects/<projectId>/apis

Confirm the requested project appears in the key grants. Do not substitute a project ID merely because it was supplied in a prompt; server authorization remains authoritative.

2. Select and understand the work

Load the work item with expanded context:

GET /api/board/projects/<projectId>/work-items
  ?include=comments,runs,usage,evidence,findings,events,handoffs
  &limit=100

Read linked TDocs pages and TSwagger contracts before planning changes that affect architecture or an integration.

3. Claim and start

PATCH /api/board/projects/<projectId>/work-items/<workItemId>/claim
{ "action": "claim", "reason": "Starting the approved implementation scope." }

PATCH /api/board/projects/<projectId>/work-items/<workItemId>/phase
{ "phase": "in_progress", "reason": "Implementation started by the terminal agent." }

Create a run before or immediately after starting execution. Keep the same run ID for status, usage, and evidence attribution.

4. Record material progress

• Add comments for decisions, constraints, or information another person needs.
• Create review findings for actionable defects.
• Attach evidence for tests, commands, diffs, commits, screenshots, and release receipts.
• Record usage with stable idempotency keys.
• Update TDocs when architecture, behavior, operations, or integration knowledge changes.
• Add a TSwagger revision when the HTTP contract changes; publish only the reviewed revision.

5. Review and handoff

PATCH /api/board/projects/<projectId>/work-items/<workItemId>/phase
{ "phase": "review", "reason": "Code, tests, TDocs, and TSwagger updates are complete." }

POST /api/board/projects/<projectId>/work-items/<workItemId>/handoffs
{ "toUserId": "<reviewer-user-id>", "note": "Review implementation and attached evidence." }

6. Finish truthfully

Complete the run with a concise outcome, record final usage, attach proof, and move the work item only to the phase actually reached. done means no required work remains—not merely that the agent stopped.