Skip to content

docs: add v1.2.0 assignee inheritance and project dot notation #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ricksaarge merged 1 commit into from
Dec 5, 2025
Merged

docs: add v1.2.0 assignee inheritance and project dot notation #5

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 15 additions & 13 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -131,7 +131,7 @@ taskmark-spec/
| Type | Pattern | Example | Notes |
|------|---------|---------|-------|
| Assignee | `@username` | `@alice @bob` | Case-insensitive, `a-zA-Z0-9_-` |
| Project | `+name[/sub]` | `+Acme/Backend` | Hierarchical with `/` |
| Project | `+name[/sub]` | `+Acme/Backend`, `+app/v1.2.3` | Hierarchical `/`, versions with `.` |
| Tag | `#tag` | `#critical #backend` | Case-insensitive |
| Due date | `due:DATETIME` | `due:2024-03-15T18:00` | ISO 8601 format |
| Estimate | `~NUM[hmd]` | `~2h`, `~30m`, `~3d` | Hours, minutes, days |
Expand Down Expand Up @@ -169,11 +169,11 @@ taskmark-spec/
### Section Headers and Inheritance

```markdown
# TODO +GlobalProject #globalTag type:value
# TODO +GlobalProject #globalTag @team type:value

## Section Name +SectionProject #sectionTag
## Section Name +SectionProject #sectionTag @alice

- [ ] Task +TaskProject #taskTag
- [ ] Task +TaskProject #taskTag @bob
```

**Inheritance Rules:**
Expand All @@ -182,19 +182,20 @@ taskmark-spec/
|---------------|----------|---------|
| Projects (`+`) | Hierarchical join with `/` | `+A` + `+B` + `+C` = `+A/B/C` |
| Tags (`#`) | Additive (all tags included) | `#api` + `#urgent` = both |
| Assignees (`@`) | Additive (all assignees included) | `@alice` + `@bob` = both |
| Key-value | Child overrides parent | Child `type:bug` overrides parent `type:feature` |

**Example:**

```markdown
# TODO +Acme #work
# TODO +Acme #work @team

## Backend +API #critical
## Backend +API #critical @alice

- [ ] Task +Database
- [ ] Task +Database @bob
```

**Task inherits:** `+Acme/API/Database`, `#work`, `#critical`
**Task inherits:** `+Acme/API/Database`, `#work`, `#critical`, `@team`, `@alice`, `@bob`

### Subtasks

Expand All @@ -206,6 +207,7 @@ taskmark-spec/
- Independent state from parent
- Projects hierarchical join
- Tags additive
- Assignees additive

```markdown
- [ ] (A) Parent task @alice +Database #critical ~8h
Expand Down Expand Up @@ -567,21 +569,21 @@ taskmark-spec/
### Section with Inheritance

```markdown
# TODO +global-project #global-tag
# TODO +global-project #global-tag @team

## Section Name +section-project #section-tag
## Section Name +section-project #section-tag @alice

- [ ] Task inherits: +global-project/section-project, #global-tag, #section-tag
- [ ] Task inherits: +global-project/section-project, #global-tag, #section-tag, @team, @alice
```

### File Link with Inheritance

```markdown
## Backend +Acme #critical
## Backend +Acme #critical @alice

[API Team](team/api.md)

# All tasks in api.md inherit: +Acme, #critical
# All tasks in api.md inherit: +Acme, #critical, @alice
```

---
Expand Down
5 changes: 0 additions & 5 deletions TODO.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,6 @@

Project roadmap and tasks for the TaskMark specification.

## v1.2.0 - Documentation Updates +taskmark-spec/v1.2.0 #documentation

- [ ] Document `@user` assignees in headers for inheritance ~1h
- [ ] Document `.` support in project names (e.g., `+app/v1.2.3`) ~30m

## Backlog +taskmark-spec/backlog

- [ ] Reference parser implementation #implementation
Expand Down
28 changes: 15 additions & 13 deletions docs/specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@
| Done date | `YYYY-MM-DD[THH:MM[:SS][±HH:MM]]` | After planned | No | N/A | ISO 8601 datetime |
| Description | Plain text | After dates/priority/state | Yes | Yes | 1-unlimited chars |
| Assignee | `@username` | In line | No | No | `a-zA-Z0-9_-` |
| Project | `+name[/sub]` | In line | No | No | `a-zA-Z0-9_-/` |
| Project | `+name[/sub]` | In line | No | No | `a-zA-Z0-9_-./` |
| Tag | `#tag` | In line | No | No | `a-zA-Z0-9_-` |
| Created date | `created:DATETIME` | In line | No | N/A | ISO 8601 datetime |
| Started date | `started:DATETIME` | In line | No | N/A | ISO 8601 datetime |
Expand Down Expand Up @@ -110,7 +110,7 @@
| Token Type | Pattern | Valid Characters | Notes |
|------------|---------|------------------|-------|
| Assignee | `@NAME` | `a-zA-Z0-9_-` | MUST follow whitespace |
| Project | `+NAME` or `+NAME/SUB` | `a-zA-Z0-9_-/` | `/` for hierarchy only |
| Project | `+NAME` or `+NAME/SUB` | `a-zA-Z0-9_-./` | `/` for hierarchy, `.` for versions |
| Tag | `#NAME` | `a-zA-Z0-9_-` | MUST NOT be section header |
| Metadata key | `KEY:` | `a-zA-Z0-9_-` | Before colon |
| Metadata value (unquoted) | `:VALUE` | Any non-whitespace | Until whitespace |
Expand Down Expand Up @@ -229,31 +229,32 @@

| Header Level | Pattern | Example |
|--------------|---------|---------|
| Top level | `# TODO` (required) | `# TODO +Acme #work` |
| Section | `## Section Name` | `## Backend +API #critical` |
| Subsection | `### Subsection Name` | `### Database +Maintenance` |
| Top level | `# TODO` (required) | `# TODO +Acme #work @team` |
| Section | `## Section Name` | `## Backend +API #critical @alice` |
| Subsection | `### Subsection Name` | `### Database +Maintenance @bob` |

**All headers MAY include metadata (projects, tags, key-value pairs).**
**All headers MAY include metadata (projects, tags, assignees, key-value pairs).**

### 5.2 Inheritance Rules

| Metadata Type | Behavior | Example |
|---------------|----------|---------|
| Projects (`+`) | Hierarchical (join with `/`) | `+A` + `+B` = `+A/B` |
| Tags (`#`) | Additive | `#api` + `#urgent` = both tags |
| Assignees (`@`) | Additive | `@alice` + `@bob` = both assignees |
| Key-value | Override | `type:bug` overrides `type:feature` |

**Example:**

```markdown
# TODO +Acme #work
# TODO +Acme #work @team

## Backend +API #critical
## Backend +API #critical @alice

- [ ] Task +Database
- [ ] Task +Database @bob
```

**Task inherits:** `+Acme/API/Database`, `#work`, `#critical`
**Task inherits:** `+Acme/API/Database`, `#work`, `#critical`, `@team`, `@alice`, `@bob`

---

Expand All @@ -268,6 +269,7 @@
| States | Independent of parent | Can differ from parent state |
| Projects | Hierarchical join | Parent `+A`, subtask `+B` → `+A/B` |
| Tags | Additive | Parent `#api`, subtask `#urgent` → both |
| Assignees | Additive | Parent `@alice`, subtask `@bob` → both |
| Key-value | Override | Child overrides parent |

**Invalid Nesting:**
Expand Down Expand Up @@ -312,13 +314,13 @@
**Example:**

```markdown
## Engineering +Enterprise #engineering type:maintenance
## Engineering +Enterprise #engineering @geordi type:maintenance

[Warp Core](team/warp.md)
[Transporters](team/transport.md)
```

**Result:** All tasks from both files inherit: `+Enterprise`, `#engineering`, `type:maintenance`
**Result:** All tasks from both files inherit: `+Enterprise`, `#engineering`, `@geordi`, `type:maintenance`

---

Expand Down Expand Up @@ -393,7 +395,7 @@
| Type | Examples |
|------|----------|
| Assignees | `@user1 @user2` |
| Projects | `+proj1 +proj2/sub` |
| Projects | `+proj1 +proj2/sub +app/v1.2.3` |
| Tags | `#tag1 #tag2` |
| Dates | `created:`, `started:`, `paused:`, `due:` |
| Recurrence | `repeat:PATTERN` or `repeat:"natural language"` |
Expand Down