idea-manager

Requirements

IDEA Manager

Structured manager for IDEAS.md — prevents drift and enforces consistent conventions for tracking ideas, learnings, and proposals.

Intentions → Commands

Quick Reference

Trigger Phrases

When the user says any of these, run idea-manager report to generate a markdown table of non-completed items:

• What's on the idea list?
• Review idea list
• Idea list
• Review IDEAS.md
• Unfinished ideas from IDEAS.md
• Status of ideas
• Idea list status
• What ideas are not completed?

Important Rules

1. Always use structured fields — Never manually edit IDEAS.md. Use idea-manager to ensure consistency and prevent corruption.

2. ID format matters — Use DOMAIN-NNN format (e.g., IDEA-001, TOOL-003, SKL-010). IDs must be unique.

3. Status lifecycle — Follow: active → pending/blocked → completed/superseded. Never skip statuses.

4. Atomic updates only — The tool uses tempfile + atomic move to prevent partial writes that can corrupt the file.

5. Document decisions — When marking an idea completed or superseded, use --decision to record why and what replaced it.

6. JSON schema validation — When using --json flag, input must be a JSON object containing both id and title fields. Well-formed JSON that doesn't match this schema (e.g., openclaw.json) will be rejected with a clear error message.

Workflow Modes

Add New Idea

idea-manager write \
  --id IDEA-001 \
  --title "Add cron failure alerts" \
  --priority high \
  --status active \
  --area cron,monitoring \
  --source "User request" \
  --details "Configure failureAlert on all cron jobs with Telegram notifications."

Required: --id, --title
Recommended: --priority, --status, --area, --details

Auto-Generate ID

Instead of specifying an explicit ID, use --auto-id to have the script calculate the next available IDEA-NNN sequence number:

idea-manager write --auto-id --title "Add cron failure alerts" --priority high --status active

This scans existing entries, finds the highest IDEA-NNN number, and generates the next one. Useful for interactive use where you don't want to manually track IDs.

Update Existing Idea

# Change status
idea-manager edit --id IDEA-001 --status completed

# Update with decision
idea-manager edit --id IDEA-001 \
  --status superseded \
  --decision "Replaced by LRN-20260810-002" \
  --details "New approach uses built-in failureAlert instead of custom monitoring."

Delete an Idea

# Delete with a decision reason
idea-manager delete --id IDEA-001 --decision "Replaced by LRN-20260822-001"

The --decision flag records why the idea was removed (recommended). The entry is permanently removed from IDEAS.md.

Archive Completed Items

# Archive all completed entries, reindex remaining
idea-manager archive

# Archive entries of a specific status
idea-manager archive  # archives completed items only; --status is restricted to 'completed'

Moves matching entries to memory/IDEAS-Archive-YYYY-MM-DD.md, removes them from IDEAS.md, and reindexes the remaining entries sequentially (IDEA-001, IDEA-002, …). The --decision field is included in the archive record when present.

Review and Search

# All active ideas
idea-manager read --status active

# Specific domain
idea-manager read --area cron

# Export for processing
idea-manager read --status active --json | jq '.[] | select(.priority=="high")'

Summary Statistics

idea-manager status

Output shows total count, distribution by status/priority/area.

Field Reference

Gotchas

• Don't edit IDEAS.md directly — Manual edits bypass validation and can cause format drift. Always use idea-manager.

• ID collisions — The tool checks for duplicate IDs and will refuse to create conflicting entries.

• JSON output for scripting — Use --json flag when piping to other tools or processing programmatically.

• Delete is permanent — idea-manager delete removes the entry from IDEAS.md and rewrites the file. The content is recoverable from git history.

• Archive reindexes — idea-manager archive reassigns sequential IDs to remaining entries. Old IDs are recorded in the archive file and the ID mapping is printed. Any related_files references are updated automatically.

• Status meanings:

  • active: Currently being worked on or relevant
  • pending: Waiting on something external
  • blocked: Cannot proceed due to dependency
  • completed: Resolved/implemented
  • superseded: Replaced by better approach

Reference: IDEAS.md Format

The file uses a consistent markdown format with frontmatter-like metadata:

## [IDEA-001] Add cron failure alerts

**Logged**: 2026-08-10T12:30:00Z
**Priority**: high
**Status**: active
**Area**: cron,monitoring
**Source**: User request
**Pattern-Key**: cron.failure-alert

Configure failureAlert on all cron jobs...

This format is automatically generated and parsed by idea-manager. Do not modify it manually.

Scripts

• scripts/ — Contains the Python implementation (idea_manager.py)

The tool is installed as idea-manager command. IDEAS.md is user data — it is auto-created on first run and lives in the workspace root. It is gitignored (not tracked in git), so each user gets their own fresh file.

Use --file /path/to/IDEAS.md to point the tool at a different file.

Further Reading

• IDEAS.md in the workspace root for all current tracked ideas.