Willyu1007 AI First Template Document Types And Roles

Document Types and Roles

This repository uses four primary document types, each with a distinct purpose and audience.

README.md (Human-Facing)

• Purpose: Human-oriented overview and orientation
• Audience: Human maintainers and new contributors
• Contains: Project description, setup instructions, links to detailed docs
• AI Behavior:
  • Read for context only
  • No AI-specific behavior rules
  • Do not treat as authoritative for AI actions
  • Only reference if an AGENTS.md explicitly directs to a specific fact

AGENTS.md (AI-Facing Strategy)

• Purpose: AI-facing strategy and scope definition
• Audience: AI systems (code models, assistants, task runners)
• Contains: Scope, allowed operations, boundaries, safety rules, relations to other AGENTS
• AI Behavior:
  • Must follow strategy defined in the most local applicable AGENTS.md
  • Start from the closest applicable AGENTS.md and obey its scope and restrictions
  • Navigate up/down/sideways as directed by the Relations section

Standard Sections (Required)

Every AGENTS.md must include these sections:

SSOT Docs (Skill Packages)

• Purpose: Single Source of Truth (SSOT) for durable, AI-facing guidance
• Audience: AI systems
• Contains: SSOT skill entrypoints (SKILL.md) plus supporting docs (supporting files, examples/, etc.)
• AI Behavior:
  • Reference for understanding concepts and patterns
  • Discover via skills/workflows (start with the repo-routing skill if unsure)
  • Do not duplicate content in AGENTS.md

Required YAML Front Matter

Only SSOT skill entrypoints (SKILL.md) require YAML front matter. Supporting docs do not require a global metadata contract.

---
name: <skill-name>
description: One-line trigger description with keywords
---

Style Requirements (Knowledge)

• Write for AI consumption: concise, structured, do/dont callouts where helpful.
• Prefer abstract flows and constraints over platform-specific commands.
• Keep AGENTS.md as strategy; keep SSOT content in skill packages (avoid duplication).

Workdocs (workdocs/ directories)

• Purpose: Scenario-local task state
• Audience: AI systems during active work
• Contains: Plans, todos, context, outcomes
• AI Behavior:
  • Read/write during task execution
  • Create for non-trivial, multi-step, or cross-module tasks
  • Archive when work is complete; promote stable outcomes into the relevant skill package under /.system/skills/ssot/**

Standard Workdocs Structure

Workdocs use a "required core + optional extensions" model to support both simple tasks and complex scenarios.

Required core (minimum 3 files):

workdocs/active/T-YYYYMMDD-slug/
  plan.md       # Current approach and next steps
  context.md    # Constraints, assumptions, key pointers
  tasks.md      # Granular TODOs and checkpoints (verifiable items)

Optional extensions (add as needed for complex scenarios):

Naming rules:

• Use tasks.md (plural) for the verifiable checklist; do not use task.md for checklists.
• Use task.md (singular) only for a brief task description, not for checklists.
• All workdocs file names use lower_snake_case.md

Related documents

• /.system/skills/ssot/repo/architecture-core-mechanisms/knowledge-metadata/SKILL.md

Converted and distributed by TomeVault — claim your Tome and manage your conversions.