# Agentmd Init

> Creates or updates AGENTS.md with standard workflow sections including Design Principles, Bead Closure, Workflow, Landing the Plane, Issue Tracking, and Agent Best Practices.

- Skill: `tomevault-io/agentmd-init` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/agentmd-init`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/agentmd-init/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/agentmd-init

---


# Agent Workflow Initialization (agentmd_init)

Initializes or updates AGENTS.md with comprehensive agent workflow sections that establish coding standards, testing requirements, issue tracking practices, and session close procedures.

## When to Use

- Starting a new project that needs agent workflow guidance
- Adding missing workflow documentation to an existing project
- Ensuring consistent standards across projects (Design Principles, Bead Closure, Testing Requirements, etc.)
- Setting up bd (beads) issue tracking guidance
- Establishing Landing the Plane procedures for clean session endings

## What Gets Added/Updated

The skill ensures these sections exist in AGENTS.md:

1. **Design Principles** - Five mandatory principles for code changes:
   - Minimal, focused changes (one feature per commit)
   - Adversarial review for complex changes
   - Automated tests per commit
   - Clear, descriptive naming
   - Modular, independently testable design
   - Root directory sacred rule

2. **Bead Closure** - Testing requirements to close issues:
   - Specific tests that validate exact requirements
   - Unit tests for new code (prevent regressions)
   - No mocks unless explicitly required
   - All tests passing
   - Code committed
   - No known bugs
   - Documentation updated

3. **Engram Workflow** (if applicable) - Process for closing beads with learning:
   - Writing specific tests
   - Creating unit tests
   - Running tests to verify
   - Committing changes
   - Using `bd close` to trigger automatic learning

4. **Workflow for AI Agents** - Step-by-step process:
   - Check ready work
   - Claim task
   - Understand requirement
   - Write test (test-first)
   - Implement
   - Verify tests pass
   - Document changes
   - Commit with tests mentioned
   - Close only when 100% complete

5. **Landing the Plane** - Session-ending checklist:
   - Review in-progress beads (only close if complete)
   - File remaining work
   - Ensure quality gates pass
   - Commit everything
   - Sync issue tracker
   - Clean git state
   - Verify clean state

6. **Issue Tracking with bd** - Guide for using beads:
   - Why bd (dependency-aware, git-friendly, agent-optimized)
   - Quick start commands
   - Issue types (bug, feature, task, epic, chore)
   - Priorities (0-4)
   - Best practices
   - Managing AI-generated planning docs in history/

7. **Agent Best Practices** - General guidelines:
   - Never start development servers
   - Verify work with tests
   - Keep commits focused and small
   - Write clear commit messages
   - Conservative approach when unsure about closure

## Usage

### Option 1: Load the skill manually

Load this skill in your session:

```bash
# The skill is at: .agents/skills/agentmd_init/SKILL.md
# This will inject the workflow guidance into your context
```

### Option 2: Use as a prompt command

When starting a new project, ask to "use the agentmd_init skill" to create/update AGENTS.md with all standard sections.

## What Happens

1. **If AGENTS.md doesn't exist**: Creates it with a project header and all standard sections
2. **If AGENTS.md exists**: Preserves all existing content and adds/updates only missing sections
3. **Maintains formatting**: Keeps consistent Markdown style with existing content
4. **Protects custom content**: Never removes or alters existing sections

## Key Principles

- **Testing is mandatory**: Every commit must have specific tests validating the functionality
- **Bead closure is conservative**: Only close when work is 100% complete and tests prove it
- **Real implementations**: Tests use actual code, not mocks (unless explicitly required)
- **Clean root directory**: All guidance goes in AGENTS.md or docs/, never status/planning files in root
- **Learning systems depend on quality**: Incomplete work creates bad learning signals

## Benefits

- ✅ Consistent agent workflow across projects
- ✅ Clear testing and closure criteria prevent incomplete work
- ✅ Structured session-ending procedures reduce state pollution
- ✅ Integration with bd (beads) for dependency-aware issue tracking
- ✅ Learning loop support (Engram/ACE framework compatible)
- ✅ Clean repository root (planning docs in history/)

## See Also

- AGENTS.md - The generated workflow guidance document
- docs/DEVELOPMENT.md - Detailed development workflows
- docs/EXPERIMENT_MANAGEMENT.md - Experiment naming and structure
- bd (beads) documentation - Issue tracking and workflow

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/sjarmak) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-14 -->