Artifact decision guide: task vs rule vs skill vs vBRIEF

[visionik]

Migrated from issue #887: #887

This topic is primarily a design/RFC discussion. Keep conceptual debate here; keep the issue as the implementation tracker for codifying the accepted decision.

---

Artifact decision guide: task vs rule vs skill vs vBRIEF

Core decision rule

If it is repeatable and mechanically checkable, make it a task.
If it changes agent behavior globally, make it a Directive rule.
If it is a multi-step agent workflow, make it a skill.
If it is structured state/spec/progress that agents and tools must exchange, make it vBRIEF.
If it is exploratory, historical, or conceptual, use another artifact.

1. Taskfile task

Use a Taskfile task when the thing is a repeatable operation that should run deterministically.

Good candidates:

• Validation gates: task check, task lint, task test, task validate
• Generated reports: stale issue report, label audit, closure-hygiene report
• Release operations: changelog promotion, tag creation, build artifacts
• Repo maintenance: link checking, schema validation, stub detection
• Any command agents currently retype or infer repeatedly

Rule of thumb:

If an agent should not have to “figure out how” every time, make it a task.

Examples for Directive:

• task check
• task test:coverage
• task spec:validate
• task release:check
• Proposed: task github:tracker-report
• Proposed: task labels:audit
• Proposed: task issues:closure-hygiene

Do not make it a task if:

• It requires judgment, interpretation, or conversation.
• It is one-off.
• It is primarily behavioral guidance rather than executable work.

2. New Directive RFC-style rule

Use a new rule when the change is a durable behavioral invariant that should constrain agents across workflows.

Good candidates:

• “Agents MUST NOT read secrets directly.”
• “Agents MUST verify linked issues actually closed after squash merge.”
• “Agents SHOULD prefer deterministic checks over prose-only reminders.”
• “Agents MUST use Taskfile targets for repeatable operations.”
• “Agents MUST NOT continue past a skill exit boundary.”

Rule of thumb:

If violating it creates recurring agent failure, and the fix is a durable behavioral constraint, make it a rule.

Rules should be:

• Short
• Normative
• Broadly applicable
• Stable across projects
• Expressed with enforcement language: !, ~, ⊗, etc.
• Backed by tests if possible

Do not make it a rule if:

• It describes a sequence of steps.
• It only applies to one specific workflow.
• It is speculative or unproven.
• It would add token tax without preventing a known failure mode.

A common Directive smell:

“We saw one failure; add a rule.”

Better:

• If it can be enforced mechanically: create a task/check.
• If it requires a repeatable workflow: create or update a skill.
• If it is truly universal behavior: add a rule.

3. New Directive skill

Use a skill when the thing is a repeatable multi-step agent workflow involving judgment, phases, gates, handoffs, or external systems.

Good candidates:

• Review cycle
• Swarm orchestration
• Roadmap refresh
• Pre-PR quality loop
• Setup/bootstrap interview
• GitHub issue triage
• Repository audit
• Release close-out
• Porting workflow
• Structured research workflow

Rule of thumb:

If an agent needs a playbook, not just a command, make it a skill.

Skills are right when the process has:

• Multiple phases
• Explicit entry/exit conditions
• Human confirmation gates
• Anti-patterns
• Required context loading
• Tool selection logic
• Error recovery
• Handoff instructions
• Reusable prompts

Do not make it a skill if:

• It is just a shell command.
• It is only a single deterministic operation.
• It belongs as a small section in an existing skill.
• It is a principle, not a workflow.

Skill vs rule:

• Rule: “MUST verify issue closure after merge.”
• Skill: “Run post-merge close-out: inspect merged PR, verify issue states, close unresolved issues or label trackers, update release notes.”

Skill vs task:

• Task: task links:check
• Skill: “Run documentation quality loop: inspect changed docs, run link checks, fix broken references, re-read output, update changelog, create PR.”

4. vBRIEF file

Use vBRIEF when the thing is structured state that needs to persist across agents, sessions, tools, or generated artifacts.

Good candidates:

• Specifications
• Plans
• Task graphs
• Progress tracking
• Agent handoff state
• Recovery checkpoints
• Machine-readable issue triage cache
• Structured roadmap/refinement state
• Playbook execution state
• Canonical source for generated Markdown

Rule of thumb:

If humans read it as Markdown but agents/tools need to consume or regenerate it reliably, use vBRIEF as the source of truth.

Directive-specific examples:

• specification.vbrief.json -> renders to SPECIFICATION.md
• plan.vbrief.json -> plan/todo/progress tracking
• continue.vbrief.json -> recovery checkpoint
• Proposed issue cache sidecars
• Structured roadmap triage state

Use vBRIEF when you need:

• Schema validation
• Stable IDs
• Machine-readable status
• Parent/child task structure
• Cross-agent handoff
• Deterministic rendering
• Auditability

Do not use vBRIEF if:

• The content is simple prose.
• It is only historical narrative.
• It is not consumed by tools or agents.
• A Taskfile task or Markdown doc is enough.
• The schema would be heavier than the artifact.

5. Other artifacts

Plain Markdown docs

Use Markdown when the artifact is primarily human-readable explanation.

Good for:

• Philosophy
• Concepts
• Reference docs
• Contributor docs
• Architecture explanation
• Design rationale
• Examples

Examples:

• CONTRIBUTING.md
• README.md
• meta/philosophy.md
• coding/security.md
• tools/taskfile.md

Rule:

If it teaches or explains, Markdown is fine. If it governs behavior, consider rule/skill/task/vBRIEF.

GitHub issue

Use an issue when the thing is work to be tracked.

Good for:

• Bugs
• Feature requests
• Cleanup tasks
• Follow-up work
• Investigation tasks
• Epics/tracker issues

Use labels/status/project fields to distinguish:

• type:bug
• type:feature
• type:epic
• type:research
• status:triage
• status:ready
• status:tracker

Rule:

If it needs prioritization, ownership, discussion, or closure, make it an issue.

GitHub Discussion

Use Discussions for open-ended design conversation that is not yet actionable.

Good for:

• Philosophy debates
• Naming/positioning
• Broad architecture exploration
• RFC incubation before implementation criteria exist

Rule:

If there is no clear “done,” start in Discussions. Promote to issue when it has acceptance criteria.

ADR

Use an ADR when the thing is a durable architecture decision.

Good for:

• “vBRIEF is the source of truth”
• “ROADMAP updates happen at release time”
• “Directive uses Taskfile as deterministic operation entrypoint”
• “Skills are workflow playbooks, not concept docs”

Rule:

If future agents need to know why a path was chosen, write an ADR.

GitHub Action / CI check

Use automation when the thing is a repo-level enforcement mechanism.

Good for:

• Link checking
• Schema validation
• Labeler
• Dependabot
• Stale policy
• PR template validation
• Required checks
• Release validation

Rule:

If humans keep forgetting it, automate it.

Decision matrix

Need	Best artifact
Repeatable command	Taskfile task
Deterministic validation	Taskfile task + CI
Universal agent behavior	Directive rule
Multi-step agent workflow	Skill
Persistent structured state	vBRIEF
Human explanation	Markdown doc
Track work	GitHub issue
Open-ended discussion	GitHub Discussion
Durable architecture decision	ADR
Repo enforcement	GitHub Action / branch protection
One-off note	Issue comment or history note

Practical examples

Scenario	Artifact
“Check all open PRs for missing issue refs”	Taskfile task
“Agents must not merge PRs without checking issue closure”	Directive rule
“Run a full PR review/fix/Greptile loop”	Skill
“Persist a multi-agent swarm’s task state and recovery point”	vBRIEF
“Explain why vBRIEF is source of truth”	ADR / Markdown
“Investigate if install path should be .deft/”	GitHub issue or Discussion
“Implement .deft/ install path”	GitHub issue + spec task
“Run release checklist”	Skill + Taskfile tasks
“Validate release artifacts exist and are non-empty”	Taskfile task + CI
“Teach agents when to choose rule vs skill vs task”	Directive rule/doc, possibly skill if workflowized

Recommended hierarchy for Directive

When adding something new, ask in this order:

1. Can this be enforced deterministically?
   • Make a task or CI check.
2. Is this a repeatable multi-step agent workflow?
   • Make or update a skill.
3. Is this durable behavior that applies broadly?
   • Add a Directive rule.
4. Is this structured state agents/tools must consume?
   • Use vBRIEF.
5. Is this just explanation or rationale?
   • Use Markdown or ADR.
6. Is this work to be done?
   • Create a GitHub issue.
7. Is this still exploratory?
   • Use GitHub Discussions or an RFC issue.

Main anti-pattern

The biggest Directive risk is turning every observed failure into a prose rule.

Better ladder:

1. Task/CI if mechanically checkable.
2. Skill if workflow-driven.
3. Rule only if broadly behavioral.
4. vBRIEF if stateful/structured.
5. Doc/ADR if explanatory.

In short:

Rules should be rare. Skills should encode workflows. Tasks should enforce repeatable checks. vBRIEF should carry structured state. Markdown should explain why.