plainweave AGENTS.md

Filigree Issue Tracker

filigree tracks tasks for this project. Data lives in .filigree/. Prefer the MCP tools (mcp__filigree__*) when available; fall back to the filigree CLI otherwise.

Workflow

# At session start
filigree session-context                            # ready / in-progress / critical path

# Pick up the next startable issue (atomic claim + transition into its working status)
filigree start-next-work --assignee <name>
# ...or claim a specific issue
filigree start-work <id> --assignee <name>

# Do the work, commit, then
filigree close <id>

Use the atomic claim+transition verbs — work_start / work_start_next (MCP) or start-work / start-next-work (CLI). Do not chain work_claim (MCP) or filigree claim (CLI) with a subsequent status update — the two-step form races against other agents; the combined verb is atomic.

Ready ≠ startable. The working status is type-specific (tasks → in_progress, features → building). Bugs start at triage, which has no single-hop transition into work (triage → confirmed → fixing), so a triage bug is ready but not directly startable: work_start on one returns INVALID_TRANSITION naming the next status, and work_start_next skips it. work_ready items carry a startable flag (plus a next_action hint when false). Pass advance=true (MCP) / --advance (CLI) to walk the soft transitions to the nearest working status automatically.

Observations: when (and when not) to use them

observation_create is a fire-and-forget scratchpad for incidental defects — things you notice outside the scope of your current task (a code smell in a neighbouring file, a stale TODO, a missing test for an edge case you happened to spot). Notes expire after 14 days unless promoted. Include file_path and line when relevant. At session end, skim observation_list and either observation_dismiss or observation_promote for what has accumulated.