The ask
From a community question: a change's tasks.md often mixes work the AI can do with work only a developer can do — creating third-party accounts, pasting secrets, hardware/physical steps, anything requiring spend or credentials. Today there's no way to tell OpenSpec "this line isn't for the AI." Original proposal was to tag lines:
- [ ] [DEV] Create a Twilio account, obtain a live API SID/token
- [ ] [DEV] Add TWILIO_AUTH_TOKEN to the local encrypted .env
- [ ] [AI] Add twilioToken + is2FAEnabled fields to prisma.schema
…with the tooling recognizing [DEV] and skipping execution.
What happens today
tasks.md is a flat checklist and nothing understands task ownership — the tooling only ever reads the checkbox state:
Stage | Behavior with a [DEV] tag
-- | --
Progress count | Counts the checkbox; the tag is invisible free text.
Apply loop | Captures the tag as part of the task description, then ignores it; the apply skill is told to "work through tasks until done or blocked."
Archive | An unchecked box = incomplete → warns (doesn't block).
So the tag works fine as a human convention today (write it, tell your agent to skip [DEV] lines), but nothing enforces or reports on it.
Why plain [DEV]/[AI] gating is the wrong layer
- Completion semantics have no clean answer. A checkbox has two states. A human task needs a third — "done by a person, not the AI." If a
[DEV] task counts toward completion and stays unchecked, archive nags forever; if it doesn't count, nothing tracks that the human did it. - Real cost is threading, not parsing. A blessed vocabulary has to run through progress-counting, the apply/verify/archive workflow templates, and
all_done logic — and those templates are pinned by golden-hash parity tests. - It's the thin end of an assignment system (
[QA], [REVIEW], assignees…), which is a much bigger product direction.
Better directions to discuss
Prerequisites, not tasks. "Create a Twilio account" is an environmental precondition, not an implementation step. Move that work out of the checklist into a plain-bullet section — the progress counter already ignores non-checkbox bullets, so the agent reads it as context but completion math stays clean. No third state, no template/counter changes.
## Manual prerequisites
- Create a Twilio account, obtain a live API SID/token
- Add TWILIO_AUTH_TOKEN to .env
Tasks
[ ] Add twilioToken + is2FAEnabled fields to prisma.schema
Recognition, not annotation. The AI already knows it can't create an account or paste a secret. One paragraph in the apply guardrail — "if a task needs human-only action (accounts, secrets, credentials, spend, hardware), don't attempt it; surface it as a handoff and continue" — solves it with zero labeling discipline from the user.
Solve it at authoring time. Teach the propose/plan step to route non-automatable work into a prerequisites section from the start. Then apply/verify/archive need no changes at all — the mixed list never gets created.
Suggested resolution
Lean toward (1) + (3): document a ## Manual prerequisites convention, taught at authoring time, working with the fact that the counter already ignores plain bullets — optionally add (2)'s guardrail paragraph as a safety net. This gives the original ask everything except machine-readable per-actor reporting ("2 human tasks left"), which nobody's currently requesting.
Open questions:
- Do people need per-actor reporting/counting, or just "AI doesn't attempt it + doesn't nag"? (Changes whether a real vocabulary is justified.)
- How common is genuine interleaving (AI → human secret → AI), where a flat prerequisites section loses ordering?
The ask
From a community question: a change's
tasks.mdoften mixes work the AI can do with work only a developer can do — creating third-party accounts, pasting secrets, hardware/physical steps, anything requiring spend or credentials. Today there's no way to tell OpenSpec "this line isn't for the AI." Original proposal was to tag lines:…with the tooling recognizing
[DEV]and skipping execution.What happens today
Stage | Behavior with a [DEV] tag -- | -- Progress count | Counts the checkbox; the tag is invisible free text. Apply loop | Captures the tag as part of the task description, then ignores it; the apply skill is told to "work through tasks until done or blocked." Archive | An unchecked box = incomplete → warns (doesn't block).tasks.mdis a flat checklist and nothing understands task ownership — the tooling only ever reads the checkbox state:So the tag works fine as a human convention today (write it, tell your agent to skip
[DEV]lines), but nothing enforces or reports on it.Why plain
[DEV]/[AI]gating is the wrong layer[DEV]task counts toward completion and stays unchecked, archive nags forever; if it doesn't count, nothing tracks that the human did it.all_donelogic — and those templates are pinned by golden-hash parity tests.[QA],[REVIEW], assignees…), which is a much bigger product direction.Better directions to discuss
Prerequisites, not tasks. "Create a Twilio account" is an environmental precondition, not an implementation step. Move that work out of the checklist into a plain-bullet section — the progress counter already ignores non-checkbox bullets, so the agent reads it as context but completion math stays clean. No third state, no template/counter changes.
[ ] Add twilioToken + is2FAEnabled fields to prisma.schema
Recognition, not annotation. The AI already knows it can't create an account or paste a secret. One paragraph in the apply guardrail — "if a task needs human-only action (accounts, secrets, credentials, spend, hardware), don't attempt it; surface it as a handoff and continue" — solves it with zero labeling discipline from the user.
Solve it at authoring time. Teach the propose/plan step to route non-automatable work into a prerequisites section from the start. Then apply/verify/archive need no changes at all — the mixed list never gets created.
Suggested resolution
Lean toward (1) + (3): document a
## Manual prerequisitesconvention, taught at authoring time, working with the fact that the counter already ignores plain bullets — optionally add (2)'s guardrail paragraph as a safety net. This gives the original ask everything except machine-readable per-actor reporting ("2 human tasks left"), which nobody's currently requesting.Open questions: