markform 0.1.16 → 0.1.18

package/docs/markform-apis.md

@@ -202,10 +202,41 @@ const result = await fillForm({
 | `maxStepsPerTurn` | `number` | `20` | Maximum AI SDK steps (tool call rounds) per turn |
 | `targetRoles` | `string[]` | `['agent']` | Roles to fill |
 | `fillMode` | `FillMode` | `'continue'` | `'continue'` or `'overwrite'` |
+| `enableParallel` | `boolean` | `false` | Enable parallel execution for forms with `parallel` batches |
+| `maxParallelAgents` | `number` | `4` | Max concurrent agents for parallel batches |
 | `callbacks` | `FillCallbacks` | `undefined` | Progress callbacks |
 | `signal` | `AbortSignal` | `undefined` | Cancellation signal |
 | `additionalTools` | `Record<string, Tool>` | `undefined` | Custom tools for agent |
 
+### Parallel Execution
+
+When a form uses `parallel` attributes on groups, you can enable concurrent execution:
+
+```typescript
+const result = await fillForm({
+  form: formMarkdown,
+  model: 'anthropic/claude-sonnet-4-5',
+  enableWebSearch: true,
+  captureWireFormat: false,
+  enableParallel: true,
+  maxParallelAgents: 4,
+  callbacks: {
+    onOrderLevelStart: ({ order }) => console.log(`Order ${order} starting`),
+    onBatchStart: ({ batchId }) => console.log(`Batch ${batchId} starting`),
+    onBatchComplete: ({ batchId, patchesApplied }) =>
+      console.log(`Batch ${batchId}: ${patchesApplied} patches`),
+  },
+});
+```
+
+**Behavior:**
+- `enableParallel: false` (default): All fields filled serially, `parallel` attributes
+  ignored. The `order` attribute still controls issue filtering.
+- `enableParallel: true`: Batch items run concurrently (up to `maxParallelAgents`).
+  Each agent runs a multi-turn loop with rejection feedback, same as the serial path.
+- If the form has no `parallel` batches, falls back to serial automatically.
+- `FillResult` shape is identical regardless of serial or parallel execution.
+
 ### FillStatus
 
 The `status` field in `FillResult` indicates success or failure:
@@ -355,6 +386,85 @@ Run a research session on a research-type form.
 
 See [runResearch.ts](../packages/markform/src/research/runResearch.ts) for full details.
 
+## Markdown Utilities
+
+Utilities for working with markdown content, particularly for plan documents with
+implicit checkboxes.
+
+```typescript
+import {
+  findAllHeadings,
+  findEnclosingHeadings,
+  findAllCheckboxes,
+  injectCheckboxIds,
+  injectHeaderIds,
+} from 'markform';
+```
+
+### findAllHeadings(markdown: string): HeadingInfo[]
+
+Find all headings in a markdown document, returned in document order.
+
+```typescript
+interface HeadingInfo {
+  level: number;        // 1-6 for h1-h6
+  title: string;        // Heading text (without # prefix)
+  line: number;         // Line number (1-indexed)
+  position: SourceRange;
+}
+```
+
+### findEnclosingHeadings(markdown: string, line: number): HeadingInfo[]
+
+Find all headings that enclose a given line position. Returns headings from innermost
+(most specific) to outermost (least specific).
+
+A heading "encloses" a line if the heading appears before the line and no heading of
+equal or higher level appears between them.
+
+### findAllCheckboxes(markdown: string): CheckboxInfo[]
+
+Find all checkboxes in a markdown document with their enclosing heading context.
+
+```typescript
+interface CheckboxInfo {
+  id?: string;                    // Existing ID from annotation
+  label: string;                  // Checkbox label text
+  state: CheckboxValue;           // Current state (todo, done, etc.)
+  position: SourceRange;          // Source position
+  enclosingHeadings: HeadingInfo[]; // Innermost first
+}
+```
+
+### injectCheckboxIds(markdown: string, options): InjectIdsResult
+
+Inject ID annotations into checkboxes that lack them.
+
+```typescript
+interface InjectCheckboxIdsOptions {
+  generator: (info: CheckboxInfo, index: number) => string;
+  onlyMissing?: boolean;  // Default: true
+}
+
+interface InjectIdsResult {
+  markdown: string;              // Modified markdown
+  injectedCount: number;         // Number of IDs added
+  injectedIds: Map<string, string>; // label -> generated ID
+}
+```
+
+### injectHeaderIds(markdown: string, options): InjectIdsResult
+
+Inject ID annotations into markdown headings.
+
+```typescript
+interface InjectHeaderIdsOptions {
+  generator: (info: HeadingInfo, index: number) => string;
+  onlyMissing?: boolean;  // Default: true
+  levels?: number[];      // Default: [1, 2, 3, 4, 5, 6]
+}
+```
+
 ## Type Exports
 
 All Zod schemas and TypeScript types are exported from the main package:

package/docs/markform-reference.md

@@ -256,6 +256,37 @@ Stateful checklists with three modes.
 | `[y]` | yes | Explicit yes |
 | `[n]` | no | Explicit no |
 
+### Implicit Checkboxes (Plan Documents)
+
+Forms designed as task lists can omit explicit field wrappers. When a form has a
+`{% form %}` tag but no `{% field %}` tags, checkboxes are automatically wrapped in
+an implicit checkboxes field.
+
+```markdown
+---
+markform:
+  spec: MF/0.1
+---
+{% form id="plan" title="Project Plan" %}
+
+## Phase 1: Research
+- [ ] Literature review {% #lit_review %}
+- [ ] Competitive analysis {% #comp %}
+
+## Phase 2: Design
+- [x] Architecture doc {% #arch %}
+- [/] API design {% #api %}
+
+{% /form %}
+```
+
+**Requirements:**
+- Each checkbox MUST have an ID annotation (`{% #id %}` or `<!-- #id -->`)
+- IDs must be unique (same rules as explicit checkboxes fields)
+- The implicit field uses ID `checkboxes` (reserved)
+- Always uses `checkboxMode="multi"` (5-state)
+- Mixing explicit fields with checkboxes outside fields is an error
+
 ### URL Field
 
 Single URL with format validation.
@@ -385,6 +416,8 @@ All fields support these attributes:
 | `required` | boolean | false | Must be filled for completion |
 | `role` | string | - | Target actor (`user`, `agent`) |
 | `priority` | string | medium | `high`, `medium`, `low` |
+| `order` | number | `0` | Fill order. Lower values filled first. Different order levels are filled in separate turns. |
+| `parallel` | string | - | Parallel batch identifier. Items with the same value may execute concurrently. Top-level only. |
 
 **Text-entry fields only** (string, number, string-list, url, url-list):
 
@@ -401,6 +434,31 @@ All fields support these attributes:
 Note: `placeholder` and `examples` are NOT valid on chooser fields (single-select,
 multi-select, checkboxes).
 
+## Harness Configuration
+
+Optional harness hints can be set in YAML frontmatter under `markform.harness`.
+All keys must be `snake_case` and all values must be numbers.
+These are suggestions — a harness may ignore or override them via API options.
+
+| Key | Type | Description |
+| --- | --- | --- |
+| `max_turns` | number | Maximum turns before stopping |
+| `max_patches_per_turn` | number | Maximum patches per turn |
+| `max_issues_per_turn` | number | Maximum issues surfaced per turn |
+| `max_parallel_agents` | number | Maximum concurrent agents for parallel execution |
+
+```yaml
+markform:
+  spec: MF/0.1
+  harness:
+    max_turns: 50
+    max_issues_per_turn: 5
+    max_patches_per_turn: 10
+    max_parallel_agents: 4
+```
+
+Unrecognized keys or non-numeric values cause parse errors.
+
 ## Documentation Blocks
 
 Add context to fields, groups, or the form.

package/docs/markform-spec.md

@@ -144,6 +144,30 @@ markform:
   When omitted, tools may infer from field roles or require explicit selection.
   This is a hint for tooling, not enforced by the engine.
 
+- `harness` (*optional*): A map of harness configuration hints that suggest execution
+  parameters to harness implementations. These are suggestions — a harness MAY ignore
+  them or override them via API options.
+
+  Supported keys (all values must be numbers, all keys must be `snake_case`):
+
+  | Key | Description |
+  | --- | --- |
+  | `max_turns` | Suggested maximum turns before stopping |
+  | `max_patches_per_turn` | Suggested maximum patches per turn |
+  | `max_issues_per_turn` | Suggested maximum issues surfaced per turn |
+  | `max_parallel_agents` | Suggested maximum concurrent agents for parallel execution |
+
+  Unrecognized keys or non-numeric values are parse errors.
+
+  Example:
+  ```yaml
+  markform:
+    spec: MF/0.1
+    harness:
+      max_turns: 50
+      max_parallel_agents: 4
+  ```
+
 **Behavioral rules (*required*):**
 
 - *required:* `form_summary`, `form_progress`, and `form_state` are derived,
@@ -255,6 +279,8 @@ Example: `pattern="^[A-Z]{1,5}$"` for a ticker symbol.
 | `label` | string | Required. Human-readable field name |
 | `required` | boolean | Whether field must be filled for form completion |
 | `role` | string | Target actor (e.g., `"user"`, `"agent"`). See role-filtered completion |
+| `parallel` | string | Parallel batch identifier. Top-level fields/groups only. See [Parallel Execution Hints](#parallel-execution-hints) |
+| `order` | number | Fill order (default: `0`). Lower values filled first. See [Fill Order](#fill-order) |
 
 The `role` attribute enables multi-actor workflows where different fields are assigned
 to different actors.
@@ -270,6 +296,11 @@ These attributes are only valid on text-entry field kinds.
 Using them on chooser fields (single-select, multi-select, checkboxes) will result in a
 parse error.
 
+**Nesting constraints:**
+- Field tags MUST NOT be nested inside other field tags
+- Nested field tags produce a parse error:
+  `Field tags cannot be nested. Found 'inner_id' inside 'outer_id'`
+
 **Example with placeholder and examples:**
 ```md
 {% field kind="string" id="company_name" label="Company name" placeholder="Enter company name" examples=["ACME Corp", "Globex Inc"] %}{% /field %}
@@ -636,6 +667,60 @@ In this example, `risk_factors.currency` is unfilled (`[ ]`) and will fail valid
 because `checkboxMode="explicit"` requires all options to have explicit `[y]` or `[n]`
 answers.
 
+##### Implicit Checkboxes (Plan Documents)
+
+Forms designed as task lists or plans can omit explicit field wrappers. When a form
+contains:
+- A `{% form %}` wrapper (or `<!-- form ... -->`)
+- No explicit `{% field %}` tags
+- Standard markdown checkboxes with ID annotations
+
+The parser automatically creates an implicit checkboxes field:
+
+| Property | Value |
+| --- | --- |
+| ID | `checkboxes` (reserved) |
+| Label | `Checkboxes` |
+| Mode | `multi` (always) |
+| Options | All checkboxes in document order |
+| Implicit | `true` |
+
+**Example:**
+```md
+---
+markform:
+  spec: MF/0.1
+---
+{% form id="plan" title="Project Plan" %}
+
+## Phase 1: Research
+- [ ] Literature review {% #lit_review %}
+- [ ] Competitive analysis {% #comp %}
+
+## Phase 2: Design
+- [x] Architecture doc {% #arch %}
+- [/] API design {% #api %}
+
+{% /form %}
+```
+
+The above form parses to a schema with a single implicit checkboxes field containing
+four options: `lit_review`, `comp`, `arch`, and `api`.
+
+**Requirements:**
+- Standard option ID rules apply (see [Identifiers](#identifiers)):
+  - Each checkbox MUST have an ID annotation (`{% #id %}` or `<!-- #id -->`)
+  - IDs MUST be unique within the implicit field
+  - Recommended: use `snake_case` slugified from label
+- ID `checkboxes` is reserved and MUST NOT be used for explicit fields
+- Nested checkboxes (indented list items) are collected as separate options
+
+**Error conditions:**
+- Checkbox without ID annotation: Parse error (same as explicit checkboxes fields)
+- Duplicate checkbox ID: Parse error (same as explicit checkboxes fields)
+- Mixed mode (explicit fields AND checkboxes outside fields): Parse error
+- Explicit field with ID `checkboxes`: Parse error (reserved ID)
+
 ##### String-List Fields
 
 String-list fields represent open-ended arrays of user-provided strings.
@@ -974,17 +1059,24 @@ Markform files may contain content outside of Markform tags. This content is han
 
 | Content Type | Policy |
 |--------------|--------|
-| HTML comments (`
+| Markdown content (headings, paragraphs, lists, etc.) | Preserved; structure must be equivalent after round-trip |
+| HTML comments (`<!-- ... -->`) | Preserved verbatim on round-trip |
+| Arbitrary Markdoc tags (non-Markform) | Parse warning, ignored (not preserved) |
 
-<!-- ... -->
+**Content preservation semantics (*required*):**
+
+- *required:* All markdown content outside of Markform tags MUST be preserved on
+  canonical serialization
+
+- *required:* The markdown structure MUST be equivalent after round-trip (same headings,
+  paragraphs, lists, code blocks, etc.)
 
-`) | Allowed, preserved verbatim on round-trip |
-| Markdown headings/text between groups | Allowed, but NOT preserved on canonical serialize |
-| Arbitrary Markdoc tags (non-Markform) | Parse warning, ignored |
+- *recommended:* Visual appearance SHOULD be preserved (same rendering output)
 
-**MF/0.1 scope:** Only HTML comments are guaranteed to be preserved. Do not rely on
-non-Markform content surviving serialization. Future versions may support full
-content preservation via raw slicing.
+- Superficial adjustments are permitted: line wrapping, whitespace normalization,
+  stylistic conventions for Markform tag formatting (attribute ordering, spacing)
+
+- The semantic content and document structure must remain intact
 
 #### Serialization Strategy
 
@@ -993,7 +1085,9 @@ requirements beyond what it provides—see [Formatting][markdoc-format]):
 
 **MF/0.1 content restrictions for canonical serialization (*required*):**
 
-To ensure deterministic round-tripping without building a full markdown serializer:
+The following restrictions apply to content *within* Markform elements to ensure
+deterministic parsing and validation. General markdown content outside of Markform
+tags is preserved via raw slicing (retaining the original text):
 
 | Content type | Restriction |
 |--------------|-------------|
@@ -1191,6 +1285,59 @@ On GitHub, all `<!-- ... -->` comments are hidden, leaving only the visible cont
 **Constraint:** Values containing the literal string `-->` require escaping or should
 use the tag syntax to avoid prematurely closing the comment.
 
+##### Parallel Execution Hints
+
+Top-level fields and groups MAY include a `parallel` attribute to indicate that they
+can be filled concurrently with other items sharing the same value.
+
+```markdown
+<!-- field kind="string" id="a" label="A" parallel="batch_1" --><!-- /field -->
+<!-- field kind="string" id="b" label="B" parallel="batch_1" --><!-- /field -->
+```
+
+**Rules:**
+- `parallel` value is an arbitrary string identifier (recommended: `snake_case`)
+- Items with the same `parallel` value form a *parallel batch*
+- Items without `parallel` remain in loose-serial mode (single agent, no enforced
+  ordering) — identical to current behavior
+- `parallel` MUST NOT appear on fields inside groups (parse error) — only on
+  top-level fields and groups
+- All items in a parallel batch MUST have the same effective `role` (parse error)
+- `parallel` is a hint — a harness MAY ignore it and fill everything in
+  loose-serial mode
+
+**Execution model:**
+```
+Without parallel: All items filled by one agent in loose-serial mode (current behavior).
+
+With parallel: Items are partitioned into two pools:
+  1. Loose-serial pool: items without `parallel`, filled by primary agent
+  2. Parallel batches: items with `parallel`, each item filled by a separate agent
+All agents (primary + parallel) run concurrently. No barriers between them.
+```
+
+##### Fill Order
+
+Fields and groups MAY include an `order` attribute (numeric) that controls the
+sequence in which the harness presents fields to the agent.
+
+```markdown
+<!-- field kind="string" id="details" label="Details" --><!-- /field -->
+<!-- field kind="string" id="summary" label="Summary" order=99 --><!-- /field -->
+```
+
+**Rules:**
+- `order` is a number (integer or float). Default: `0`.
+- Lower `order` values are filled first. Fields at the same order level are
+  filled in loose-serial order (agent chooses).
+- The harness MUST NOT surface issues for `order=N` fields until all fields at
+  `order<N` are complete (answered, skipped, or aborted).
+- Fields at different order levels are always filled in separate agent turns.
+- A field inside a group with `order` MUST NOT specify a different `order`
+  (parse error). Use separate groups for different order levels.
+- `order` composes with `parallel`: all items in a parallel batch MUST have the
+  same effective `order` value (parse error otherwise).
+
 * * *
 
 ## Layer 2: Form Data Model
@@ -1374,6 +1521,8 @@ interface FieldGroup {
   // Note: `required` on groups is not supported in MF/0.1 (ignored with warning)
   validate?: ValidatorRef[];  // validator references (string IDs or parameterized objects)
   children: Field[];          // MF/0.1/0.2: fields only; nested groups deferred (future)
+  parallel?: string;          // Parallel batch identifier
+  order?: number;             // Fill order (default: 0). Applies to all child fields.
 }
 
 type FieldPriorityLevel = 'high' | 'medium' | 'low';
@@ -1384,6 +1533,8 @@ interface FieldBase {
   required: boolean;             // explicit: parser defaults to false if not specified
   priority: FieldPriorityLevel;  // explicit: parser defaults to 'medium' if not specified
   validate?: ValidatorRef[];     // validator references (string IDs or parameterized objects)
+  parallel?: string;             // Parallel batch identifier (top-level only)
+  order?: number;                // Fill order (default: 0). Lower = filled first.
 }
 
 // NOTE: `required` and `priority` are explicit (not optional) in the data model.
@@ -1420,7 +1571,9 @@ interface Option {
   id: Id;
   label: string;
 }
+```
 
+```typescript
 type CheckboxMode = 'multi' | 'simple' | 'explicit';
 
 interface CheckboxesField extends FieldBase {
@@ -1966,6 +2119,16 @@ YAML keys use snake_case for readability and consistency with common YAML conven
 | `tag` | `DocumentationBlock` | `DocumentationTag` values | Identifies doc block type |
 | `nodeType` | `IdIndexEntry` | `'form' \| 'group' \| 'field'` | Identifies structural element type |
 
+**Special IDs:**
+
+These IDs have special meaning but can also be used explicitly. When used explicitly, uniqueness
+is still enforced (only one field or group with each ID).
+
+| Special ID | Purpose | Explicit Use |
+| --- | --- | --- |
+| `default` | Implicit group for ungrouped fields | When explicit, ungrouped fields merge into it |
+| `checkboxes` | Implicit checkboxes field for plan documents | When explicit, used instead of implicit creation |
+
 ##### Field Kind Mappings
 
 **`string-field`** — Single string value
@@ -2584,6 +2747,38 @@ isRetryableError(error)    // LLM error with retryable=true
 `ParseError` is exported as an alias for `MarkformParseError` for backward compatibility.
 Use `MarkformParseError` in new code.
 
+#### Execution Plan
+
+An **execution plan** partitions top-level form items into a loose-serial pool and
+zero or more parallel batches:
+
+```typescript
+interface ExecutionPlan {
+  /** Items without `parallel` — filled by primary agent in loose-serial mode */
+  looseSerial: Array<{ itemId: Id; itemType: 'field' | 'group' }>;
+
+  /** Parallel batches — each item filled by a separate concurrent agent */
+  parallelBatches: Array<{
+    batchId: string;
+    items: Array<{ itemId: Id; itemType: 'field' | 'group' }>;
+  }>;
+}
+```
+
+**Computation:** Walk top-level items (fields and groups) in document order:
+- If item has no `parallel`: add to the loose-serial pool
+- If item has `parallel`: add to the batch with that ID (create batch if new)
+
+**Execution:** The primary agent fills loose-serial items. For each parallel batch,
+one agent per item is spawned. All agents (primary + batch agents) run concurrently.
+When all complete, patches are merged and validation runs.
+
+**Order-based filtering:** The harness partitions items by their effective `order`
+value (default `0`). Issues for fields at `order=N` are only surfaced after all fields
+at `order<N` are complete (answered, skipped, or aborted). This ensures fields at
+different order levels are always filled in separate agent turns, so higher-order fields
+see completed lower-order field values in the form markdown.
+
 * * *
 
 ## Layer 4: Tool API & Interfaces

package/examples/movie-research/movie-deep-research-mock-filled.form.md

@@ -35,7 +35,7 @@ markform:
       - Skip fields if data unavailable (older films may lack some metrics)
       - For box office, use millions (e.g., 100.5 for $100.5M)
       - Add notes for any missing, confusing, or unclear information
-  harness_config:
+  harness:
     max_issues_per_turn: 5
     max_patches_per_turn: 15
 ---

package/examples/movie-research/movie-deep-research.form.md

@@ -35,7 +35,7 @@ markform:
       - Skip fields if data unavailable (older films may lack some metrics)
       - For box office, use millions (e.g., 100.5 for $100.5M)
       - Add notes for any missing, confusing, or unclear information
-  harness_config:
+  harness:
     max_issues_per_turn: 5
     max_patches_per_turn: 15
 ---

package/examples/parallel/parallel-research.form.md

@@ -0,0 +1,57 @@
+---
+markform:
+  spec: MF/0.1
+  title: Company Research (Parallel)
+  description: "Demonstrates parallel and order attributes for concurrent form filling."
+  roles:
+    - agent
+  role_instructions:
+    agent: "Research the company and fill in all fields."
+  harness:
+    max_turns: 10
+    max_parallel_agents: 4
+---
+{% form id="company_research" title="Company Research (Parallel)" %}
+
+{% description ref="company_research" %}
+A company research form that uses `parallel` for concurrent deep research
+and `order` to sequence synthesis after data gathering.
+{% /description %}
+
+{% group id="overview" order=0 %}
+
+{% field kind="string" id="company_name" label="Company Name" role="agent" required=true %}{% /field %}
+
+{% field kind="string" id="company_overview" label="Company Overview" role="agent" %}{% /field %}
+
+{% /group %}
+
+{% group id="financials" parallel="deep_research" order=0 %}
+
+{% field kind="string" id="revenue" label="Annual Revenue" role="agent" %}{% /field %}
+
+{% field kind="string" id="margins" label="Margin Analysis" role="agent" %}{% /field %}
+
+{% /group %}
+
+{% group id="team" parallel="deep_research" order=0 %}
+
+{% field kind="string" id="leadership" label="Team & Leadership" role="agent" %}{% /field %}
+
+{% /group %}
+
+{% group id="market" parallel="deep_research" order=0 %}
+
+{% field kind="string" id="tam" label="TAM" role="agent" %}{% /field %}
+
+{% field kind="string" id="competitors" label="Competitors" role="agent" %}{% /field %}
+
+{% /group %}
+
+{% group id="synthesis" order=10 %}
+
+{% field kind="string" id="overall" label="Overall Assessment" role="agent" required=true %}{% /field %}
+
+{% /group %}
+
+{% /form %}

package/examples/plan-document/plan-document-markdoc.form.md

@@ -0,0 +1,35 @@
+---
+markform:
+  spec: MF/0.1
+  title: Sprint Tasks
+  description: "Plan document example using Markdoc syntax instead of HTML comments."
+  roles:
+    - user
+  role_instructions:
+    user: "Update task status as you complete work."
+---
+{% form id="sprint_tasks" title="Sprint Tasks" %}
+
+{% description ref="sprint_tasks" %}
+A sprint task list using Markdoc tag syntax. Both Markdoc (`{% %}`) and
+HTML comment (`<!-- -->`) syntaxes are equivalent in Markform.
+{% /description %}
+
+## Backend
+
+- [ ] Implement user authentication {% #auth %}
+- [ ] Add rate limiting {% #rate_limit %}
+- [ ] Set up database migrations {% #db_migrations %}
+
+## Frontend
+
+- [ ] Create login page {% #login_page %}
+- [ ] Add form validation {% #form_validation %}
+- [ ] Implement dark mode {% #dark_mode %}
+
+## DevOps
+
+- [ ] Configure CI/CD pipeline {% #cicd %}
+- [ ] Set up monitoring {% #monitoring %}
+
+{% /form %}

package/examples/plan-document/plan-document-progress.form.md

@@ -0,0 +1,47 @@
+---
+markform:
+  spec: MF/0.1
+  title: Project Plan
+  description: "Example plan document using implicit checkboxes - no explicit field wrappers needed."
+  roles:
+    - user
+    - agent
+  role_instructions:
+    user: "Review the plan and update task status as work progresses."
+    agent: "Track task completion and update checkbox states."
+---
+<!-- form id="project_plan" title="Project Plan" -->
+
+<!-- description ref="project_plan" -->
+A project plan demonstrating Markform's implicit checkboxes feature.
+When a form has no explicit field tags, checkboxes are automatically
+collected into an implicit `checkboxes` field.
+<!-- /description -->
+
+## Phase 1: Research
+
+- [x] Review existing documentation <!-- #review_docs -->
+- [x] Analyze competitor solutions <!-- #competitor_analysis -->
+- [x] Interview stakeholders <!-- #stakeholder_interviews -->
+
+## Phase 2: Design
+
+- [x] Create architecture document <!-- #arch_doc -->
+- [x] Design API specification <!-- #api_spec -->
+- [/] Review design with team <!-- #design_review -->
+
+## Phase 3: Implementation
+
+- [*] Set up development environment <!-- #dev_setup -->
+- [ ] Implement core functionality <!-- #core_impl -->
+- [ ] Add unit tests <!-- #unit_tests -->
+- [ ] Add integration tests <!-- #integration_tests -->
+
+## Phase 4: Release
+
+- [ ] Write user documentation <!-- #user_docs -->
+- [ ] Perform security audit <!-- #security_audit -->
+- [-] Deploy to staging <!-- #staging_deploy -->
+- [ ] Deploy to production <!-- #prod_deploy -->
+
+<!-- /form -->