Comprehensive research document exploring a lightweight CLI wrapper
around Markform for simple, file-based task management. Covers:
- Comparison of Beads vs simpler file-based approach
- File format design using Markform checkboxes
- CLI command structure (create, add, check, list, archive)
- Implementation architecture as a thin Markform wrapper
- Multiple design alternatives with tradeoffs
- Integration patterns with agents and existing tools

Extends the research document with comprehensive analysis of:
- Typical Beads workflow (5-15 issue implementation planning)
- Feature-by-feature mapping to Tasklist (easy/medium/hard)
- Multi-paragraph description support (tested working)
- Cross-reference patterns and conventions
- Dependency handling through ordering and phases
- Complete example of task list as implementation plan
- Summary of what works well vs needs conventions vs requires extensions
Key finding: Current Markform capabilities are sufficient for MVP.
Field-level docs support multi-paragraph content, multiple checkbox
fields enable phase-based organization, and checkbox ordering provides
implicit sequencing.

Extends research document with additional design considerations:
- Using Markform notes for item descriptions (existing feature)
- Structured YAML notes for Beads-like metadata per item
- Multi-checkbox mode as default (5 states: todo/active/incomplete/done/na)
- Atomic file writes (already implemented in Markform)
- Frontmatter vs footnotes placement patterns
- Updated CLI command mapping for multi-mode states
Key finding: Markform's existing notes system can attach descriptions
to individual checklist items without spec changes. Multi-mode provides
agent-friendly in_progress state mapping.

- Change `[>]` to `[*]` for active state (spec uses asterisk)
- Add missing `state` field to Note interface documentation
- All checkbox tokens now match Markform spec:
 - `[ ]` todo, `[x]` done, `[/]` incomplete, `[*]` active, `[-]` na

@chatgpt-codex-connector chatgpt-codex-connector bot left a comment

Address PR review feedback:
- Update Note interface to match engine (coreTypes.ts:56-62)
- Clarify that Note.ref supports field/group/form only, NOT options
- Note spec vs implementation gap (spec has state field, engine doesn't)
- Mark per-option notes as "proposed extension" throughout
- Update examples to use field-level refs that work today
- Clarify item_metadata is a proposed extension, not current spec
- Update recommendations to use field-level documentation blocks

New section exploring automatic conversion of plain Markdown checklists
to valid Markform. Key features:
- `markform wrap` command to convert .md to .form.md
- ID generation from headings or positional fallback
- Option ID generation via slugify algorithm
- Checkbox mode defaulting to multi (5 states)
- Edge case handling (nested lists, mixed content, idempotency)
- Workflow integration with validation for CI/CD
This enables drafting plans in familiar Markdown, then converting to
structured Markform for reliable agent manipulation.