Skip to content

AGENTS.md

Latest commit

 

History

History
212 lines (159 loc) · 7.98 KB

AGENTS.md

File metadata and controls

212 lines (159 loc) · 7.98 KB
Raw

Agent Instructions

Memory: Hindsight bank

This repo uses the hindsight-memory skill. Project memory lives in the Hindsight bank named in .bank (do not edit by hand).

  • Recall against the project bank AND coding-knowledge at the start of relevant tasks (parallel calls).
  • Retain learnings as atomic, self-contained, clear memories tagged user/feedback/project/reference.
  • Cross-project rules go in coding-knowledge as memories tagged coding-rule (not as directives — directives are not recallable).
  • Use retain (async); avoid sync_retain in normal flow (it blocks).
  • Manual ops: /hindsight-memory-operations (subcommands: bootstrap, migrate [path], status, disable, enable, forget <query>).
  • Never touch banks not prefixed with coding-.
  • Disable per-repo: /hindsight-memory-operations disable or add enabled: false to .bank.
  • Disable globally: HINDSIGHT_MEMORY=off or remove ~/.claude/hindsight-memory.enabled.

Project Management with Mycelium

This project uses Mycelium (myc) for task and epic management.

Quick Reference

# Initialize mycelium in this project (creates .mycelium/ directory)
myc init

# Create an epic (a large body of work)
myc epic create --title "Feature X" --description "Build feature X"

# Create tasks within an epic
myc task create --title "Implement Y" --description "Build the implementation for Y" --epic 1 --priority high --due 2025-12-31

# Task priorities: low, medium, high, critical
# Task status: open, in_progress, closed
# Mark a task as in progress (there is no `task start`; use update):
myc task update 1 --status in_progress

# List tasks. `myc list` (top-level) shows a TREE with dependencies and epic
# grouping — use it to see the overall state. `myc task list` is a flat list.
myc list
myc task list
myc task list --epic 1
myc task list --overdue
myc task list --blocked
myc task list --all          # include closed tasks

# Manage dependencies (task 1 blocks task 2)
myc task link blocks --task 1 2
myc deps show 2

# Close tasks (blocked tasks cannot be closed without --force)
myc task close 1

# Assign tasks
myc assignee create --name "Alice" --github "alice"
myc task assign 1 1

# Link to external resources
myc task link github-issue --task 1 "owner/repo#123"
myc task link github-pr --task 1 "owner/repo#456"
myc task link url --task 1 "https://example.com"

# Project overview
myc summary

# Export data
myc export json
myc export csv

Data Model

  • Epic: A large body of work with a title and optional description (e.g., a feature or milestone)
  • Task: A unit of work with a title and optional description, optionally linked to an epic
  • Dependency: Task A blocks Task B (B cannot close until A is closed)
  • Assignee: Person assigned to a task (can have GitHub username)
  • External Ref: Link to GitHub issues/PRs or URLs

Git Tracking

The .mycelium/ directory contains the SQLite database and should be committed to git:

git add .mycelium/
git commit -m "Add mycelium project tracking"

Follow-ups (myc followup, alias myc fu)

Lightweight scratch table for non-blocking "oh-by-the-way" items captured mid-work — bugs, questions, ideas, things the user should look at later. Separate from tasks (no epic/priority/deps/assignee). Most follow-ups are resolved by the user, not the agent.

myc followup add "body text"                # capture (body required)
myc followup add "body text" --title "tag"  # optional short title
myc fu add "short form alias works too"

myc followup list                           # all (default)
myc followup list -o                        # only active (open + in_progress)
myc followup list -c                        # only closed (done + wontfix)
myc followup list --status done             # exact status

myc followup show <id>                      # full detail
myc followup next                           # lowest-ID active (agent loop)
myc followup count                          # JSON: {open, in_progress, done, wontfix}

myc followup start <id>                     # → in_progress
myc followup done <id> [--reason "..."]     # → done
myc followup wontfix <id> [--reason "..."]  # → wontfix
myc followup reopen <id>                    # → open

myc followup edit <id> --body "new body" [--title -|"new title"]
myc followup append <id> "more context"     # timestamped, preserves existing
myc followup rm <id> [--force]
myc followup promote <id> [--epic N] [--priority high]  # convert to task

Agent rule — end-of-task follow-up check (MANDATORY)

At the end of every mycelium-tracked unit of work (closing a task, finishing a user-requested change that touched myc state), the agent MUST:

  1. Run myc followup list --format json (or myc followup count --format json).
  2. If active > 0, surface them to the user before wrapping:

    "Before we wrap — N open follow-up(s): [titles/bodies]. Want me to handle any now, or leave for later?"

  3. Never silently process them. Always ask.

myc task close itself also prints a one-line reminder, but the agent should still proactively check.

Use myc followup add during work to capture anything you notice but shouldn't act on right now.

For AI Agents

When working on this project:

  1. At the START of a task, reconstruct state instead of relying on memory: myc list (tree with dependencies) and myc followup list -o (open items).
  2. Check blocked tasks: myc task list --blocked
  3. Create tasks for new work: myc task create --title "..." --description "..." --epic N
  4. Mark a task in progress while you work on it: myc task update N --status in_progress
  5. Capture incidental observations as follow-ups: myc followup add "..."
  6. At end of task: myc followup list and surface open ones to the user
  7. Mark tasks complete when done: myc task close N
  8. Use --format json for machine-readable output: myc task list --format json

Mental Frameworks for Mycelium Usage

1. INVEST — Task Quality Gate

Before creating or updating any task, validate it against these criteria. A task that fails more than one is not ready to be written.

Criterion Rule
Independent Can be completed without unblocking other tasks first
Negotiable The what is fixed; the how remains open
Valuable Produces a verifiable, concrete outcome
Estimable If you cannot size it, it is too vague or too large
Small If it spans more than one work cycle, split it
Testable Has an explicit, binary done condition

If a task fails Estimable or Testable, convert it to an Epic and decompose.

2. DAG — Dependency Graph Thinking

Before scheduling or prioritizing, model the implicit dependency graph.

Rules:

  • No task moves to in_progress if it has an unresolved upstream blocker
  • Priority is a function of both urgency and fan-out (how many tasks does completing this one unlock?)
  • Always work the critical path first — not the task that feels most urgent

Prioritization heuristic:

score = urgency + (blocked_tasks_count × 1.5)

When creating a task, explicitly ask: "What does this block, and what blocks this?" Set dependency links in Mycelium before touching status.

3. Principle of Minimal Surprise (PMS)

Mycelium's state must remain predictable and auditable at all times.

Rules:

  • Prefer idempotent operations — update before you create; never duplicate
  • Check before write — search for an equivalent item before creating a new one
  • Always annotate mutations — every status change, priority shift, or reassignment must carry an explicit reason field
  • No orphan tasks — every task must be linked to an Epic; every Epic to a strategic goal
  • Deletions are a last resort; prefer cancelled status with a reason

The state of Mycelium after any operation must be explainable to another agent with zero context.