Agent Actionable Tasks

When to Use

Trigger: "what's approved", "get actionable tasks", "what should I work on", "agent:get:actionable-tasks", "pick up next task", "approved incomplete items"

Use this when you need to find work that a person has reviewed and approved from session compactions (the record a session leaves behind of what it did and what it left unfinished — see /alignment-harness:harness-setup or the compactions skill for how those get written).

How It Works

Session compactions contain incompleteItems — unfinished work from past coding sessions. The person reviews these and marks the ones worth doing as approved, usually with a priority score (1-100). You query the approved list, pull context, then act.

If this project has its own service for this (a database, an admin tool, a project-management integration — see /alignment-harness:harness-setup), query it with the shapes shown below; they carry over unchanged. Otherwise, use the local fallback throughout this skill: a folder of JSON compaction records that alignment-harness records compactions prints the path to. Each record is one session's compaction; incompleteItems is an array on it with the same fields described here. This fallback always works, with no setup.

Get Approved Tasks

If you have your own service configured (example shape — replace the URL and auth with your own):

curl -s -H "x-api-key: $YOUR_API_KEY" \
  "https://<your-api-server>/actionable-incomplete-items?limit=10&byPriority=true"

Local fallback (no service configured — reads the JSON records directly):

RECORDS_DIR=$(alignment-harness records compactions)
node -e '
const fs = require("fs"), path = require("path");
const [, , dir, status, limit] = process.argv;
let items = [];
for (const f of fs.existsSync(dir) ? fs.readdirSync(dir).filter((n) => n.endsWith(".json")) : []) {
  let rec; try { rec = JSON.parse(fs.readFileSync(path.join(dir, f), "utf8")); } catch { continue; }
  (rec.incompleteItems || []).forEach((it, i) => {
    if ((it.status || "pending") === status) {
      items.push({ ...it, itemIndex: i, parentSessionId: rec.conversationId || f.replace(/\.json$/, ""),
        parentTitle: rec.title, parentRepo: rec.repo, parentIntent: (rec.scopeDeclaration || {}).intent });
    }
  });
}
items.sort((a, b) => (b.priority || 0) - (a.priority || 0));
console.log(JSON.stringify(items.slice(0, Number(limit) || 10), null, 2));
' "$RECORDS_DIR" approved 10

Change approved to pending or dismissed to see other statuses; drop the priority sort and sort by file mtime instead if you want most-recently-touched first.

Response Shape

Each item returns:

Field	Description
title	The task title
content	Full task description
priority	1-100 (higher = more important)
status	approved (ready for work)
itemIndex	Position in parent's incompleteItems array
parentSessionId	Session compaction this came from
parentTitle	Parent compaction title
parentRepo	Which repo the work is in
parentIntent	Overarching intent of the parent session
contextInstructions	Read this first — tells you how to pull full context
creatorSessionId	Original agent session ID (for resume)
creatorCwd	Working directory of original session

Required Workflow: Context Before Action

NEVER start working on an item without pulling its surrounding context first.

For each item:

1. Read the contextInstructions field — it tells you exactly what to do
2. Pull the full compaction. If you have an institutional-memory search set up (agent_find/agent_read or your own equivalent — see /alignment-harness:harness-setup), use it. Otherwise, read the local record directly: cat "$RECORDS_DIR"/<file matching parentSessionId>.json
3. Review the overarching intent — understand what the session was trying to achieve
4. Check howToConsumeThisWorkProduct (if present) — the original session may have left specific guidance
5. Then act on the incomplete item with full context

Mark Work Complete

With your own service:

curl -s -X PUT -H "Content-Type: application/json" -H "x-api-key: $YOUR_API_KEY" \
  "https://<your-api-server>/compactions/<parentSessionId>/incomplete-items/<itemIndex>" \
  -d '{"status": "completed"}'

Local fallback:

RECORDS_DIR=$(alignment-harness records compactions)
node -e '
const fs = require("fs"), path = require("path");
const [, , dir, sessionId, itemIndex] = process.argv;
const file = fs.readdirSync(dir).find((f) => f.includes(sessionId) && f.endsWith(".json"));
if (!file) { console.error("no local record found for", sessionId); process.exit(1); }
const p = path.join(dir, file);
const rec = JSON.parse(fs.readFileSync(p, "utf8"));
rec.incompleteItems[Number(itemIndex)].status = "completed";
fs.writeFileSync(p, JSON.stringify(rec, null, 2));
console.log("marked complete:", p);
' "$RECORDS_DIR" "<parentSessionId>" "<itemIndex>"

Priority Tiers

Range	Tier	Meaning
70-100	High	Do this first — high leverage, time-sensitive
40-69	Medium	Important but not urgent
1-39	Low	Nice to have, do when available

Status Lifecycle

pending → approved → completed
              ↘ dismissed

• pending — extracted from session, not yet reviewed
• approved — the person reviewed it and marked it ready for agent work
• completed — agent finished the work
• dismissed — the person decided it's not worth doing

Reviewing and Approving

If you have an admin UI wired to your own service, manage items there. Without one, review and approve directly on the local records: open the JSON file in alignment-harness records compactions for the session, and set each incompleteItems[i].status to approved, dismissed, or a priority value by hand (or write a small script using the same read/modify/write pattern shown above). There's nothing more to it than editing that field — no server required.

---

Maintenance Intents (Recurring Tasks)

Some session-compaction intents represent recurring maintenance work (dependency audits, test-suite health checks, performance monitoring). These get flagged and tracked with a due-date cadence, separately from one-off incomplete items.

Get Due Maintenance Intents

With your own service (example shape):

curl -s -H "x-api-key: $YOUR_API_KEY" \
  "https://<your-api-server>/maintenance-intents/due?limit=5"

Local fallback: maintenance intents are their own small JSON records, one per recurring item, in the folder alignment-harness records maintenance-intents prints. Each record: { "title", "description", "regularityDays", "lastCompletedAt", "leverageScore", "priority", "sourceSessionId", "contextInstructions" }. Compute overdueDays yourself: overdueDays = daysSince(lastCompletedAt) - regularityDays (0 or negative means not due yet).

RECORDS_DIR=$(alignment-harness records maintenance-intents)
node -e '
const fs = require("fs"), path = require("path");
const dir = process.argv[2];
const now = Date.now();
const items = (fs.existsSync(dir) ? fs.readdirSync(dir).filter((f) => f.endsWith(".json")) : []).map((f) => {
  const rec = JSON.parse(fs.readFileSync(path.join(dir, f), "utf8"));
  const lastMs = rec.lastCompletedAt ? new Date(rec.lastCompletedAt).getTime() : 0;
  const daysSince = (now - lastMs) / 86400000;
  return { ...rec, file: f, overdueDays: Math.round(daysSince - (rec.regularityDays || 0)) };
}).filter((r) => r.overdueDays >= 0).sort((a, b) => b.overdueDays - a.overdueDays);
console.log(JSON.stringify(items.slice(0, 5), null, 2));
' "$RECORDS_DIR"

Each item returns:

• title, description — what to do
• regularityDays — cadence (e.g. every 14 days)
• overdueDays — how many days overdue (0 = due today)
• leverageScore, priority — scoring
• sourceSessionId — original session compaction to read for context
• contextInstructions — read this first

Required Workflow

1. Read contextInstructions on each item
2. Pull the source compaction (if sourceSessionId is set): via your institutional-memory search if you have one, or the local record directly, same as above
3. Do the maintenance work
4. Log completion:

With your own service:

curl -s -X POST -H "Content-Type: application/json" -H "x-api-key: $YOUR_API_KEY" \
  "https://<your-api-server>/maintenance-intents/<id>/complete" \
  -d '{"completedBy": "agent", "notes": "summary of what was done", "sessionId": "your-session-id"}'

Local fallback — update the record's lastCompletedAt (this is what recalculates when it's next due):

node -e '
const fs = require("fs");
const [, , file, notes] = process.argv;
const rec = JSON.parse(fs.readFileSync(file, "utf8"));
rec.lastCompletedAt = new Date().toISOString();
rec.notes = notes;
fs.writeFileSync(file, JSON.stringify(rec, null, 2));
console.log("logged completion:", file);
' "$RECORDS_DIR/<file>.json" "summary of what was done"

Reviewing

Without an admin UI, edit the maintenance-intent JSON files directly the same way as the incomplete items above — status changes, leverage scoring, regularity adjustment, and completion notes are all just fields on the record.