Open
Conversation
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
Contributor
Coverage Report for packages/markform
File CoverageNo changed files found. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: be7beedf05
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Comment on lines
+1173
to
+1177
| interface Note { | ||
| id: NoteId; // e.g., "n1", "n2" | ||
| ref: Id; // target ID (field, group, form, or option) | ||
| role: string; // who created (agent, user, system) | ||
| state?: 'skipped' | 'aborted'; // optional: links note to skip/abort action |
There was a problem hiding this comment.
This section describes Note.ref as supporting option IDs and adds an optional state field for skip/abort (lines 1173–1177), but the current engine Note type only supports refs to fields/groups/forms and has no state property (packages/markform/src/engine/coreTypes.ts:56-61). If Tasklist is designed around per-option notes or skip/abort metadata in notes, the current parser/serializer will drop or reject that data. Consider updating the brief to match the existing spec, or clearly mark these as proposed extensions.
Useful? React with 👍 / 👎.
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds a comprehensive research document exploring the design of Tasklist (
taskl), a lightweight CLI tool that wraps Markform for simple, file-based task management.Key additions:
docs/project/research/current/research-tasklist-cli-design.mdcreate,add,check,list,archive)Highlights:
notesfor item descriptions (no spec changes needed)checkboxMode="multi"as default (5 states: todo/active/incomplete/done/na)Test plan
[*]for active, not[>])statefield)