Normalize Org documentation and task-state skills #16

New issue

Open

opened 2026-08-22 06:49:12 +00:00 by lost-rob0t · 0 comments

lost-rob0t commented

2026-08-22 06:49:12 +00:00

(Migrated from github.com)

Parent: #13

Goal

Define clean, non-overlapping canonical skill boundaries for the remaining Org-oriented backlog before implementation.

Candidates

org-docs
maintain-org-agenda
gpt-todos

Required boundaries

`org-docs`

Own repository/user documentation authoring in Org mode.

Org first.
Markdown only when explicitly requested or required by the destination.
Discover and follow the repository's existing documentation style.
Keep structure and source blocks native to Org when Org is the target.
Do not absorb TODO synchronization or agenda maintenance.

`maintain-org-agenda`

Own durable Org agenda/TODO maintenance.

read the complete target Org file before mutation when practical;
preserve stable IDs and provenance;
distinguish active, idea, waiting, completed, cancelled, and superseded states;
update materially equivalent tasks instead of duplicating them;
do not create active TODOs from speculation;
do not own repository-specific sync transport unless that transport is the task.

`gpt-todos`

Own the repository-specific synchronization contract around lost-rob0t/gpt-todos.

synchronize before editing when the workflow requires it;
bidirectional, conflict-aware synchronization;
preserve stable IDs/provenance and Org task states;
refuse silent overwrite on ambiguous conflict;
link to maintain-org-agenda semantics instead of duplicating generic Org task rules;
keep deployment/sync mechanism portable where possible and explicitly scope owner-specific compatibility.

Format gate

Each retained skill uses the canonical skills/<id>/SKILL.md contract:

2–8 comma-separated keywords in description;
concise body, preferably ~80 lines or less;
compatibility only for real requirements;
detailed sync/reference material outside the main body when it would bloat activation context.

Acceptance

org-docs is documentation-only;
maintain-org-agenda contains generic task-state semantics;
gpt-todos contains only the repository/sync specialization and refers outward for generic agenda semantics;
no duplicate RAGE/loop behavior is introduced;
later implementation can proceed without merging these three into one giant context brick.

Parent: #13 ## Goal Define clean, non-overlapping canonical skill boundaries for the remaining Org-oriented backlog before implementation. ## Candidates - `org-docs` - `maintain-org-agenda` - `gpt-todos` ## Required boundaries ### `org-docs` Own repository/user documentation authoring in Org mode. - Org first. - Markdown only when explicitly requested or required by the destination. - Discover and follow the repository's existing documentation style. - Keep structure and source blocks native to Org when Org is the target. - Do not absorb TODO synchronization or agenda maintenance. ### `maintain-org-agenda` Own durable Org agenda/TODO maintenance. - read the complete target Org file before mutation when practical; - preserve stable IDs and provenance; - distinguish active, idea, waiting, completed, cancelled, and superseded states; - update materially equivalent tasks instead of duplicating them; - do not create active TODOs from speculation; - do not own repository-specific sync transport unless that transport is the task. ### `gpt-todos` Own the repository-specific synchronization contract around `lost-rob0t/gpt-todos`. - synchronize before editing when the workflow requires it; - bidirectional, conflict-aware synchronization; - preserve stable IDs/provenance and Org task states; - refuse silent overwrite on ambiguous conflict; - link to `maintain-org-agenda` semantics instead of duplicating generic Org task rules; - keep deployment/sync mechanism portable where possible and explicitly scope owner-specific compatibility. ## Format gate Each retained skill uses the canonical `skills/<id>/SKILL.md` contract: - 2–8 comma-separated keywords in `description`; - concise body, preferably ~80 lines or less; - `compatibility` only for real requirements; - detailed sync/reference material outside the main body when it would bloat activation context. ## Acceptance - `org-docs` is documentation-only; - `maintain-org-agenda` contains generic task-state semantics; - `gpt-todos` contains only the repository/sync specialization and refers outward for generic agenda semantics; - no duplicate RAGE/loop behavior is introduced; - later implementation can proceed without merging these three into one giant context brick.